WYSIWYG DocBook Editor?

DocBook duck colophon Those of you out there writing DocBook, especially those who do not do a lot of DocBook editing, what open source WYSIWYG DocBook editors do you use?

What DocBook authoring tools to you recommend to folks just getting started with DocBook? For example, what would you recommend for a software developer or architect who has not necessarily worked with a lot of non-WYSIWYG authoring tools? The DocBook authoring tools Wiki page seems to have been lost.

Supported solutions do exist, such as Syntext Serna, XMLmind, and Oxygen XML Editor. What about open source authoring tools, though? Perhaps you have set up XWiki with Wikbook.

Thanks for your suggestions.

ForgeRock: Case Study & White Paper templates

ForgeRock logo Core documentation rarely covers everything you want and need to know about building a solution. Core documentation can get you going on your laptop or in the lab. Yet, if your project is big or ambitious, you no doubt want to work with an expert partner who can help you take the project from idea to deployment.

Short case studies and white papers can help you get a feel for what a partner knows, and where the partner’s specific expertise lies. A short case study or white paper can be fairly quick for a partner to write after a successful implementation.

Of course to finish you have to get started. Sometimes technical experts who are great in their area feel challenged when presented with the blank wiki or word processor page. Therefore I have posted a draft How To on getting started with a case study or white paper, including proposed outlines for both.

Hope some of you find it useful. Feel free to login and change the content where you see room for improvement.

Right size examples?

Nothing illustrates a point as well as a good example. Sometimes even a mediocre example illustrates a point better than several paragraphs of text.

Sample code

Trouble comes when the example is not complete enough to test automatically. One change in naming can make the code silently out of date.

Trouble also arises when the example is so realistic that an untrained eye cannot determine which trees are important in the forest of information.

The example above is too short to compile, but still full of extra information that could distract a reader from the essential points of getting a connection from the factory, binding as Babs Jensen, and finally closing the connection.

How have you solved this problem in your docs?

OpenDJ: LDAP API, Tools, and Examples

OpenDJ Community Logo Late Thursday and early this morning Matt updated the OpenDJ community site to bring you links and descriptions, and explanations about the OpenDJ LDAP SDK.

The LDAP SDK, slated to become officially available in version 2.5, includes a modern Java API for LDAPv3, command-line tools for measuring performance and carrying out LDAP operations, and examples that demonstrate how to use the API.

Let us know how you are getting along with the SDK on the OpenDJ mailing list.

OpenDJ SDK: man pages

OpenDJ community logoThe network was down when I arrived at the office Tuesday morning. So I started filling in some man pages to fix a bug that Matt had opened.

After filling in the pages quickly and cobbling together some examples, I had a look (e.g. cd opendj3; mvn pre-site; man -M man -M  target/docbkx/manpages/dev-guide/OpenDJ-Dev-Guide/ modrate). I am pleasantly surprised by how well the DocBook XSL stylesheets lay out the pages in .roff and in HTML. The PDF needs work, though, probably some customizations. (Is the default termlength for a variablelist really 24 characters?)

So far the pages are not packaged into the build. Here’s a .zip of the 7 pages I did Tuesday.

The Examples sections are minimal so far. Should break tradition and put the Examples section near the top of the pages rather than at the end? Does anybody out there actually use man pages any more?

Core Documentation Author’s Guide

ForgeRock community logoMore core docs outlines are taking shape. I had not taken time out, however, to explain how to help write the content.

My first stab at a Core Documentation Author’s Guide can be found on the Developer Community Wiki.

The guide touches on getting started, contributing docs to a project, and finding and fixing doc bugs. There is also a section on starting your own doc project. I am not sure what I left out. If you are starting from scratch, let me know so I can show you what I have found so far.

As I wrote Monday, “Feel free to improve this guide.”

OpenAM: New Community Site

OpenAM logoThe OpenAM community site is now live at http://openam.forgerock.org/, alongside the OpenICF and OpenDJ community sites.

The sources for the OpenAM site are are visible under http://sources.forgerock.org/changelog/openam/trunk/opensso/openam-site/. If you have commit rights to the subversion repository, you can participate in updating and improving the site. I do not think there is a cron job yet to rebuild the site automatically when the sources are updated, but that should come. In the meantime no doubt somebody on the Dev list can push out an update.

All of the previous OpenAM web locations remain in place. If you were going to the wiki through openam.forgerock.org, however, update your bookmark to point to https://wikis.forgerock.org/confluence/display/openam/Home.