[Bug 283734] Documentation Best Practices
Bugzilla Link | 283734 |
Status | NEW |
Importance | P3 enhancement |
Reported | Jul 16, 2009 13:03 EDT |
Modified | Apr 23, 2010 04:55 EDT |
Description
I recently sent an email to the architecture council mailing list to spark some thoughts on how to crowdsource our documentation process across Eclipse projects. I also blogged about this based on some of my experience in moving the way PDE handles documentation:
http://eclipsesource.com/blogs/2009/07/13/crowdsourcing-documentation-at-eclipse/
This prompted some response from David Carver who blogged about XML based approaches:
http://intellectualcramps.blogspot.com/2009/07/wysiwyg-xml-editting.html
I think a good approach would be to collect some documentation best practices we can share with Eclipse projects. As the architecture council, we should try to recommend good options for Eclipse projects when it comes to documentation. First, it would be good to collect how various Eclipse projects handle their documentation currently. Here are the questions I asked in the email:
- how is it sourced (e.g., html, docbook, dita, wiki)\
- general process (special doc team or just committers?)\
- level of outside contributions
Here are my findings so far:
The Xtext project at Eclipse uses WikiText documents in CVS
The Mylyn project sources documentation from Eclipsepedia and uses Wikitext to transform to Eclipse help
The PDE project is considering moving to the Mylyn approach (listed above)
The CDO project uses DITA and Serna
The XSL Tools project uses DocBook and transforms into Eclipse help
The WTP project uses DITA apparently (?)
Another aspect of documentation that interests me is projects that have FAQs up. For example, the Mylyn project has a nice FAQ:
http://wiki.eclipse.org/index.php/Mylyn_FAQ
As does the EMF project:
http://wiki.eclipse.org/EMF-FAQ
Is this a practice that we should be recommending to Eclipse projects?