Code review policy proposal: Document it!

[MarkTraceur]

So, there's a problem with our current documentation. It's on GitHub.

Now, that on its own isn't necessarily bad, but there are two resulting issues:

1. It's all online, no offline documentation.
2. You cannot contribute documentation in parallel to code, you have to either contribute the docs to any new hooks before your pull request is accepted or after, and neither of those is an awesome choice.

Possible solutions:

1. Include documentation in the repo, in the doc/ directory. This means no huge effort, except for moving the existing docs over, which isn't too hard. It also means an easy way to do code review--if the new hook doesn't include a patch of doc/plugin-api.txt, don't accept the patch (and of course give a reason!)
2. Build a system that allows conditional, asynchronous commits to some external documentation source. This could be a MediaWiki instance, maybe the GitHub wiki (but I can't be sure it would be easy), or whatever. Basically someone would need to periodically run a script (cron job?) that checked for newly-merged pull requests, then conditionally added documentation (or changed the state of existing documentation) that was tied to those pull requests. This isn't totally perfect, because it's fake-async (check every 5 minutes, could have 4 minutes 59 seconds of fail, check every 5 seconds, could use a lot of power and resources).

Ideally, go for number 1. Let me know what you think.

[jhollinger]

+1. I think we should keep the docs in /doc (in Mardown or something). Then we use the Github Repo Hooks http://developer.github.com/v3/repos/hooks/ - probably this one - https://help.github.com/articles/post-receive-hooks/ - to trigger a doc regeneration (somewhere) on every commit.

Of course someone would need to commit to running that server...

[MarkTraceur]

Since the docs are currently in Markdown, that seems like a good plan. I'm not sure we'd need to further generate documentation, we can just start linking the current docs into the repository's current version of the right page(s)--right?

[marcelklehr]

The problems are the links, which are currently absolute. Pages in the wiki link to each other using https://github.com/Pita/etherpad-lite/wiki/Page-name. We'll have to change all links.

The Node.js team uses a very neat system for their docs: https://github.com/joyent/node/tree/master/doc/api

[MarkTraceur]

marcel, that's exactly what we could do--GitHub is even kind enough to render the markdown for you when you visit those files.

And yes, it would take some editing, but we can do it! :)

[marcelklehr]

The tool, that powers the magic, lives at https://github.com/joyent/node/tree/master/tools/doc

[marcelklehr]

I created a new upstream branch docs:

https://github.com/Pita/etherpad-lite/tree/docs/doc/api

[MarkTraceur]

+++

Good stuff. Closing.

If this could get merged, it would be awesomesauce.