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
On Wed, Jul 10, 2013 at 1:17 AM, Cosmin Lehene <[EMAIL PROTECTED]> 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.