| Re: [eclipse.org-architecture-council] Crowdsourcing Documentation at Eclipse |
Hi Chris, In Xtext we use WikiText and have all the sources in CVS. I can only recommend using WikiText. It's nice to edit and we can derive Eclipse Help as well as PDF from that. Also we were able to add a special syntax to it, with which one can refer to Java classes from the documentation. In HTML it generates a link to the WebView of CVS. Also because the documentation is in the workspace any renaming of Java identifiers will automatically be done in the documentation as well. That is pretty nice. Our development turnaround is, that whenever we change the source we add corresponding tests as well as update or add stuff to the documentation. It's hard to keep this in sync but it's a must. In order to make maintenance easier the documentation has to have a low redundancy and kept relatively short (a.k.a. reference documentation). The problem with documentation is the added redundancy. Documentation needs to be kept in sync with the software systems otherwise it is a big problem. While writing documentation is some work, keeping it up to date is even more work. Therefore I think it needs to be done by people which are totally committed. Community can help, though. Cheers, Sven On Jul 14, 2009, at 2:52 AM, Chris Aniszczyk wrote: Hey guys, I have another issue that I think may interest the Architecture Council... |