[eclipse.org-architecture-council] [Bug 283734] New: Documentation Best

[bugzilla-daemon@xxxxxxxxxxx]

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.