[osmosis-dev] Documentation in Git

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

[osmosis-dev] Documentation in Git

Brett Henderson
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:

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
[hidden email]
https://lists.openstreetmap.org/listinfo/osmosis-dev
Reply | Threaded
Open this post in threaded view
|

Re: [osmosis-dev] Documentation in Git

Michal Migurski-2
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 <[hidden email]> 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:

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
[hidden email]
https://lists.openstreetmap.org/listinfo/osmosis-dev


_______________________________________________
osmosis-dev mailing list
[hidden email]
https://lists.openstreetmap.org/listinfo/osmosis-dev