[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
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.


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... 

I recently blogged about potentially crowdsourcing documentation at Eclipse:

It would be interesting to hear stories from various project teams to how they handle documentation. In terms of:
    1) how is it sourced (e.g., html, docbook, dita, wiki)
    2) general process
    3) level of outside contributions

It's my current opinion that documentation is not in the best shape it can be at Eclipse. I think we can do better by looking at our user community to do some of the work. We have a lot of early adopters at Eclipse and people willing to contribute... we just need to make it easier in my opinion.



Chris Aniszczyk | EclipseSource Austin | +1 860 839 2465
http://twitter.com/eclipsesource | http://twitter.com/caniszczyk
eclipse.org-architecture-council mailing list

IMPORTANT: Membership in this list is generated by processes internal to the Eclipse Foundation.  To be permanently removed from this list, you must contact emo@xxxxxxxxxxx to request removal.