I like the idea of improving our documentation. Help is very much appreciated in this area (but of course the problem is that the people who experience the holes almost by definition can't fill them in). So even just pointing out areas that aren't covered is really helpful.
We are in a sort of awkward stage this week because we have a 0.8 beta release but no detailed docs on its internals. WRT your specific proposals. I don't think we should do the documentation with each feature because I think that tends to lead to a bunch of little documents one for each change. I think we effectively get this out of JIRA+wiki today. This usually serves as a fairly complete design doc + commentary be others. It is pretty hard to get information out of this format for a new user, though. We do version control documentation but we can't physically version control it with the code because the code is in git and Apache only allows SVN as a mechanism for publishing to xxx.apache.org. :-( Instead what about this: we add a new release criteria for documentation completeness. It would be good to formalize the release criteria anyway. Informally they are something like 1. Developers think it is feature complete 2. Unit tests pass 3. Integration/stress tests pass 4. Some production usage It would be good to add to this list (5) documentation up-to-date and not do a release without this. It is debatable whether this should apply to beta releases, but probably it should. We can certainly apply it to the final 0.8 release if people are on board. -Jay On Wed, Jul 10, 2013 at 1:17 AM, Cosmin Lehene <cleh...@adobe.com> wrote: > I'm not sure if there's already a guideline like this, but I wouldn't it > make sense to have it in order to keep documentation in sync with the code? > Also, having this type of documentation as part of the codebase to allow > proper versioning might be a good idea as well. > > Cosmin >
