New Eclipse Project Handbook

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

This entry was posted in Eclipse 101, EDP, Education, Project Management and tagged , , . Bookmark the permalink.

12 Responses to New Eclipse Project Handbook

  1. vogella says:

    Where do I find the source and the build chain to convert it to PDF and HTML?

  2. jmini says:

    Do you really mean Asciidoc? Not Asciidoctor?
    Asciidoctor is definitively the leading implementation of AsciiDoc format.

    Asciidoctor (and the corresponding maven plugin and its dependencies) was approved as official “build” dependencies for documentation purpose at the Eclipse foundation CQ 9720.

    I will check if I can help you with a build setup using Asciidoctor. My guess is that the PDF support there is much better than with Asciidoc.

    @vogella:
    I found the sources:
    http://git.eclipse.org/c/www.eclipse.org/projects.git/tree/handbook/source

    • waynebeaton says:

      If you found the source, then you must have also noticed the makefile which invokes Asciidoctor. I actually did start with Asciidoc and switched after running into a couple of bugs and some problematic licensing.

      As I understand it, Asciidoc is the correct name for the file format and spec, and Asciidoctor is an implementation. AFAIK, I’m using the term correctly. Let me know if I’m wrong.

      • Dan Allen says:

        Wayne,

        You’re spot on! As a veteran of the standards process in software (CDI), I recognized early on the need to keep the language and the implementations separate in name. As of now, Asciidoctor is the front-runner and reference implementation for AsciiDoc. As tools get created for AsciiDoc, I expect other parsers to crop up that are needed in other contexts (such as in Eclipse). Admittedly, we don’t yet have a specification (or at least a definition) for the language, but that is something I plan to pursue.

        The only correction I’ll draw your attention to is that the “D” is uppercase in the name of the language (i.e., AsciiDoc). But I’m not going to get all “Java EE” about it😉

        Great write up! Don’t hesitate to reach out to the Asciidoctor community if you need help or advice. It’s such a great group of people, and we’re glad to have you among us!

      • waynebeaton says:

        I’ll try to be more careful with the name. I’m one of those old guys who knows _Smalltalk_, so I know a little bit about misused capitalization in names…

  3. Pingback: Technology Behind the new Eclipse Project Handbook | Eclipse Hints, Tips, and Random Musings

  4. vogella says:

    Also a feedback to the content of your book. You are still describing the piggy back CQs. Will there be soon a new new handbook? AFAIK the foundation decided to remove this requirement.

    • waynebeaton says:

      The requirement for piggyback CQs still exists. We (the Eclipse Foundation) have a mandate to build some infrastructure to automatically generate a list of third-party dependencies for IP Logs. We’ll be able to do this for some significant subset of our projects (e.g. those using OSGi+Orbit). Piggyback CQs will still exist, but hopefully we’ll be able to eliminate the need for most of them. I’ll update the documentation accordingly when we have this implemented.

      https://bugs.eclipse.org/bugs/show_bug.cgi?id=475400

  5. jmini says:

    > I’ve started poking at a Maven build solution. It appears that the Maven plugins do a better job with PDF generation. I haven’t investigated why (maybe they use a more recent drop of Apache FOP).

    @Wayne:
    This is because they do not use FOP but Prawn (http://prawnpdf.org).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s