[osmosis-dev] Documentation in Git

[Michal Migurski]

Brett, this is great idea and I support it.

I have also found the Wiki documentation updates to be a bit of a slog, and would welcome having the docs closer to the code. PRs could modify the appropriate portions of code as well, which can help us promote better and more complete contributions.

The link you shared below might be dead now, but your description sounds right to me.

-mike.

----------------------------------------------------------------
michal migurski- contact info and pgp key:
sf/ca            http://mike.teczno.com/contact.html

> On May 19, 2020, at 4:24 AM, Brett Henderson <brett at bretth.com> wrote:
> 
> Hi Folks,
> 
> Background
> With Michal breathing some life into the Osmosis project again it's great to see the recent PR activity.
> 
> In my years maintaining the project, there were a number of things that made reviewing and incorporating PRs tedious from my side.  I made many little changes over time to make this easier, not least of which were the docker-based build/tests and Travis CI to allow anybody to verify their changes.
> 
> But one area that was always a pain was keeping the documentation up to date.  Contributors were hesitant to make changes to the wiki until changes were approved and I often found it easier to make the changes myself than to chase people.  A number of the current pending PRs will require documentation changes.
> 
> I think it would be easier to maintain if the docs were maintained alongside the code itself in Git.  Putting the docs on the OSM wiki made sense at the time, but times and tooling have changed.
> 
> Proposal
> Would anybody object to the docs being served out of GitHub?  I have done an automatic conversion of the Mediawiki markup to Asciidoc and checked it into a branch to see what it looks like:
> https://github.com/brettch/osmosis/blob/markdown-doc/usage.adoc <https://github.com/brettch/osmosis/blob/markdown-doc/usage.adoc>
> 
> Options
> I initially tried Markdown but the lack of support for auto-generating a table of contents makes it far from ideal.  Asciidoc syntax _does_ support a table of contents.
> 
> The doc is currently one huge file (same as the wiki page) but it can be split into multiple files (I'd suggest one per module/plugin).  While this would help reduce the need for a table of contents I still think it's useful.
> 
> The current asciidoc file is a bit messy and uses what I find to be weird heading syntax but that can be cleaned up if this is a good path forward.
> 
> Thoughts?
> Brett
> _______________________________________________
> osmosis-dev mailing list
> osmosis-dev at openstreetmap.org
> https://lists.openstreetmap.org/listinfo/osmosis-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstreetmap.org/pipermail/osmosis-dev/attachments/20200602/84d40824/attachment.htm>