OpenDJ: Dev Guide inside the Javadoc?

OpenDJ Community LogoMatt Swift suggested that instead of having a separate Developer’s Guide for the OpenDJ LDAP SDK, we add the dev guide into the Javadoc.

Java developers’ IDEs already provide direct access to the Javadoc. So this idea addresses one justification for printable documentation — you can keep reading even when offline — preventing you from having to search. At the same time you can still find the Javadoc we post with an online search.  Committing doc into the code also makes it slightly easier for SDK builders like Matt to notice when making a change that affects the documentation.

Perhaps most importantly this idea leads to the “dev guide” matching the modules you actually use. In other words, if we put dev guides in the Javadoc, then when you build a Maven project that grabs org.forgerock.json.resource, i18n-framework, opendj-ldap-sdk, you get just the doc you need without having to leave your IDE. Not only lists of packages, classes, and methods, but also how-tos and so forth.

I’m still figuring out what it means in detail to, “Add the dev guide into the Javadoc.” Clearly not all of the content goes into the code. No doubt a good part of the content sits alongside the body of the code, next to or in overview.html in the main/javadoc/ folder of the LDAP SDK source.

What’s your take on the idea?

Advertisements

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