For a very long time, I’ve wanted to completely rewrite our documentation for projects and committers. I finally gave it a big push last quarter and have completed a first big revision. There’s still more work to do, but I believe that the new document is very close to being the more-or-less complete “how to run an Eclipse project” document that we’ve needed for a while.
https://www.eclipse.org/projects/handbook/
I decided to compose the document using Asciidoc. I honestly can’t remember specifically why I selected Asciidoc over, say, Markdown, but using this format affords me some options that just aren’t available in the wiki or in traditional HTML.
For one, Asciidoc lets me do variable substitution and conditional inclusion. I’ve used these abilities to use one set of source materials to generate three different forms for the content: one for each of Eclipse, PolarSys, and LocationTech (note that I’ll likely move the PolarSys and LocationTech versions closer to their respective forges). Further, technology exists that makes it easy to turn each of these forms into PDFs (though, I’m still wrestling with some challenges regarding the images being rendered too large in PDFs). PDF support is more of a nice-to-have thing for those among us who really love printed documentation.
I’ll be spending time this quarter identifying and redirecting our existing content to the new document. My intent is to have this new documentation completely take over the old by the end of September.
If you notice problems with the content of the handbook, please open a bug against Community > Process prefixed with [handbook].
