Upayavira wrote:
GOALS
<snip/>
G4. Make submitting documentation a more straight forward process. I haven't yet looked at the ins and outs of the xdocs, but I know from the times I tried to find the documentation in the checked out tree that I was unable to figure out how it worked.
TOOLS / TECHNIQUES
<snip/>
1)Does all this actually make the documentation any better?
2)Should any effort towards documentation ATM go into improving its *quality* or improving its {searchability|updateability|scaleability|auto-generateability}
Unless the proposal will (also) lead to simple way of adding documentation (and I'm thinking about only slightly more difficult than the wiki), I think this process will result in a technical overhaul without improving the quality of the documentation.
As we discussed at the hackathon, I think both are concerns that interrelate, and effort can be applied separately to either.
True, but, at the moment all discussions about documentation tend to sway into the technical area and the actual writing is forgotten.
As it is, we have a complex system that few people know how to operate. I've written docs, but I've never deployed them to the site. This acts as a dis-incentive to existing and potential documentation writers.
Put them in the wiki! Why haven't you done so, yet? :-)
Other than that, we have a xdocs system that does work, and a wiki that works. We can use right now to write better docs. We just need to make the effort.
By all means, do implement this proposal if everyone feels it improves the infrastructure of the documentation. I will immediately agree to any proposal that will simplify the documentation generation process which will improve the update frequency.
However, we should also think about how to get the quality of the documentation updated and how to encourage potential documentation writers to actually sit down and produce the actual text.
Bye, Helma
