|[eclipse.org-architecture-council] [Bug 283734] New: Documentation Best Practices|
https://bugs.eclipse.org/bugs/show_bug.cgi?id=283734 Product/Component: Community / Architecture Council Summary: Documentation Best Practices Product: Community Version: unspecified Platform: PC URL: http://eclipsesource.com/blogs/2009/07/13/crowdsourcing- documentation-at-eclipse/ OS/Version: Mac OS X Status: NEW Severity: enhancement Priority: P3 Component: Architecture Council AssignedTo: eclipse.org-architecture-council@xxxxxxxxxxx ReportedBy: zx@xxxxxxxxxxxxxxxxx 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? -- Configure bugmail: https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are the assignee for the bug.
Back to the top