[OH-Dev] Mid-month check-in: Sat 3/17, 4PM Eastern / 1 PM Pacific

[Asheesh Laroia]

Excerpts from Daniel Mizyrycki's message of Wed Mar 21 21:08:14 -0400 2012:
> 
> Hi everybody
> 
> I sent a new pull request with the markdown documents translated.

Merged!

> Some suggestions
> 
> * Move all documentation to /docs and possibly have a symlink to docs 
> (like README.rst) so they will be part of the official documentation. 
> (One caveat is that Sphinx and ReadTheDocs work as expected as root for 
> the documents is /docs, but github assumes root at the project level, so 
> links to repo documents do not render correctly. We could point to 
> ReadTheDocs to work around the issue, but this adds a dependency :( )

Oh, Github.

So the thing about symlinks is that they don't seem to work on Windows,
even though git "supports" them, which leads to oddities. If you can test
that adding a symlink is fine for people on Windows who clone the repo,
that'd be great, but I remember problems before.

I see now that we did make README.rst a symlink; I'm curious what that does
on Windows!

I would say yes, let's move all documentation to docs/, except leave a README.rst
that simply says, "For documentation, look in the docs/ directory."

As for Github linking, I would say let's make them work properly in Sphinx first,
and see if we can get Github to fix its parsing of restructured text.
In particular, I think their parsers for these text formats are actually
on the web and freely licensed, so it would be quite possible to submit a
pull request to them.

> * Add an authors.rst or/and contributors.rst file on the repo.

I like this idea. I'd say contributors.rst but whatever's most common in rST-land.

> Some people have shown interest to help with docs. How would you like we 
> move forward?

I would say:

* Discuss docs-related ideas on the mailing list and/or IRC

* Submit patches (with git format-patch, either to the mailing list or
  a ticket) or pull requests (on Github.com)

Given what we've seen so far, probably you'll prefer the Github pull request route.
I'll rebase those to be against current origin/master, sanity-check, and push!

Does that seem like a usable workflow?

-- Asheesh.