A Techie Tech Writer Blog

Mozilla Labs has announced the winners of the Contacts Design Challenge, which posed the question to designers of "What are the interesting uses of having a complete list of all your contacts and relationships in your browser, for both local browser applications and services on the web?" The design concepts honored by the judging panel are great, and put forward many useful ideas. Go take a look and then come back here.

None of the design concepts quite addresses the use case that I've recently felt a need for, which is defining groups of contacts from multiple sources, to use within web applications.

Since I've started working remotely from home, I sometimes choose to go sit and work in one of several local coffee shops, for a change of scenery and some live interaction. I know a number of other remote and self-employed workers, who I know also work from coffee shops sometimes. It would be great if we could coordinate so that some of us are at the same coffee shop at the same time. There are web-based services like Foursquare and Yelp that support sending notifications about one's location. But I don't want to require all my coffee buddies to join yet another web service. Some of them are on Facebook, but I don't want to annoy my out-of-town Facebook friends with an update every time I visit a coffee shop. Some of them are on Twitter, but I don't want to end up on Please Rob Me by broadcasting to the universe that I'm not at home. For some of my contacts, I just have an email address, or a mobile phone number that I could send a text message to.

What I want is to not only have all my contacts from various sources aggregated, as in Toby Shorin's design concept, but to define groups of contacts, regardless of the source of the contact. Then, when I want to send an update to members of that group, the software automatically takes care of sending that update to each member of the group, in a way appropriate to the source of the contact. Better yet, sending to those groups should be available to web applications, so that I could tell Foursquare to notify my Coffee Buddies group, just as it currently can update my Facebook or Twitter accounts.

That's what I want. Now I just need to get Mozilla Labs to make it happen.

Here's an example of using the FLOSS Manuals' AJAX API to embed a remix of chapters from different manuals into this blog post. The embedded remix combines chapters from the How to Bypass Internet Censorship and Firefox manuals.

This is a work in progress that I'm tweaking. The API is beta.

Select an item in the left panel to read it in the right panel.

Atlassian, the maker of the Confluence enterprise wiki and the JIRA issue tracker, are selling licenses of those two programs for up to 5 users for $5. Support is renewable for $5 per year. Forever.

Details are on the Atlassian website. Thanks to Sarah Maddox for publicizing this.

Sure, there are open source wikis and issue trackers you can get for free. You might even be able to get decent support for them. But this is almost free, and proceeds will be donated to Room to Read, which builds libraries and schools in the developing world.

The offer lasts through Friday, April 24th, or when Atlassian reaches its fundraising goal, whichever comes first.

I'm getting one of each, and I'll decide what to do with them later.

Given my recent immersion in using Sphinx for technical documentation (and other uses, such as training exercises), I was quite interested to read Doug Hellmann's article on Writing Technical Documentation with Sphinx, Paver, and Cog. While I'm familiar with some of the tools he mentions (such as SVN for source control and reStructured Text for mark-up), I hadn't heard of Paver (a "make" replacement) or Cog (a tool for capturing program output).

Cog would have come in extremely handy when I had to update a bunch of code examples in the Traits User Manual because the format of the validation exception message changed. I'll definitely keep Doug's hack in mind when updating that manual in the future.

I just came across iShift's list of 22 Most Used Free Fonts by Professional Designers. These fonts are all gratis to use; some are also open licensed (libre), so you can modify them if you want. The point of iShift's ambiguously worded title is that these are all professionally designed and widely used. (They may or may not be the free fonts that are most used by professional designers.)

I've been spending a fair amount of my work time lately enhancing the training materials for Enthought's Python programming classes. One thing that I've come up with is a way to produce nice-looking handouts for programming exercises from the Python source code files that are used for the exercises.

The Python language supports the notion of documentation strings ("docstrings"), which are special comments that are associated with classes, methods, functions, and source files, and that can be displayed by the Python interpreter and used to generate API documentation (much like Java doc comments). Documentation strings are delimited by three double quotation marks ("""). This is also the delimiter used for multi-line data strings in Python.

For our Python programming classes, the exercises are programming problems, where the student is given a "starting" source file that contains a description of the problem, as well as initial code such as imports of necessary libraries or definitions of data to be used. The student is expected to fill in the source file with a working program that solves the problem. We also provide a separate "solution" file, that contains a working solution to the problem; students can compare their solutions to it, or use it for reference if they get stuck.

The set of exercises for a given class depends on the learning modules to be covered in that class, as well as customization of the class for a particular client company. For example, the content of some of the exercises can be tailored to the client's industry or domain of knowledge. In the past, to prepare a handout of exercises for a given class, the instructor would copy and paste the problem descriptions from the chosen exercises into a single text file, and then simply print copies of the text file. This was functional, but tedious to produce and not a pretty result.

In the system I set up, the exercise descriptions in the handouts are generated by Sphinx from the docstrings in the problem starting files. The docstrings themselves are formatted using reStructuredText ("reST" for short), which is a wiki-like yet powerful plain-text markup syntax. Sphinx interprets the reStructuredText, and can generate HTML or LaTeX output. For the exercise handouts, I run Sphinx with the LaTeX option , and then run pdflatex to generate a PDF of the handout.

To handle multiple learning modules in one handout, I use the nested TOC tree feature of Sphinx. The main "toctree" for the handout references separate documents for the problems and solutions. (All problems are listed first, followed by all solutions, rather than interleaving problems and solutions.) The problems and solutions documents each contain a "toctree" that references a problems or solutions document for each learning module. The module-specific problems documents then pull in the problem description from each exercise starting file, using a reST "include" directive to get just the docstring, which is interpreted for formatting. The module-specific solutions documents get the entire content of the solution file, using a "literalinclude" directive so that it is not interpreted. This diagram may help with understanding this description:



To add or remove learning modules, the instructor can modify the references in the top-level exercises and solutions documents. To add or remove exercises, they can modify the references in the module-level exercises and solutions documents.

As "single-sourcing" solutions go, this is pretty grubby. I'm not about to claim that is will scale to boatloads of content, or, really, work for anything other than this limited application. But it's way cooler than the previous copy-and-paste solution.

Mike Hughes has an excellent article on UXMatters.com on PDF Manuals: The Wrong Paradigm for an Online Experience. He gives a great summary of why print-oriented manuals make for lousy online documentation. But he goes beyond carping about PDFs to lay out requirements for what an online documentation system should contain. He spells out four "essential" requirements for online documentation:

• easily navigable across an entire set of information


• easily searchable across a user-designated scope


• easily readable topics


• easily printable by topic or topic clusters

I think it's debatable whether the last point is essential: Whether users need to be able to print topics depends on the particular project. In some cases, users have no need to refer to topics off-line, and so don't need to print them. However, I would add one more requirement to this list, at least for online help for software applications (vs. documentation that happens to be delivered online):

• easily invokable from within the context of the application — in other words, context-sensitivity.

For many tech writers, who produce either Microsoft HTML Help, or some variant of WebHelp from a proprietary HAT, this discussion is of academic interest at best. Their tool meets these criteria already, and they don't have to worry about it.

In my ongoing quest for the perfect open source browser-based online help solution, it's helpful to have this short list of criteria. Mike's article describes how Eclipse help meets his criteria; it also meets the context-sensitivity criterion, too. If you're developing for the Java platform, it's hard to beat. For browser-based help, the leading contender is OmniHelp, which comes close, but falls short on the ability to restrict the scope of searches, and the ability to print groups of topics.

The cool new documentation tool in the Python world is Sphinx, which generates HTML, HTML Help, and LaTeX formats. The LaTeX format can be converted to PDF using, well, LaTeX. The source files that Sphinx reads are in reStructured Text (reST), a wiki-like but powerful plain-text mark-up syntax. ReST and Sphinx are now used to generate the documentation for Python itself, replacing the earlier LaTeX-based format. Sphinx is being used by a growing list of Python-based projects.

ReST is a fairly general syntax, but the key to its power lies in "directives", through which new constructs can be added without adding primary syntax. Sphinx has harnessed that power to provide document-processing features not native to reST, such as:

• Combining multiple source files to create a single output document


• Table-of-contents generation


• Index generation (based on marked entries)


• Cross-references


• Cross-referencing of glossary terms

Sphinx adds many constructs that are specific to programming documentation, such as semantic mark-up for modules, classes, functions, variables, and so on; these constructs enable easy cross-referencing of such items. Sphinx also has special support for code examples, function signatures, and grammar productions.

If you want to customize the look of the output, Sphinx supports a templating system, based on Jinja.

There is an extension that supports conditional inclusion of content. In theory, this extension could be used for "conditional text", though it appears that it would be awkward to use extensively.

A couple of built-in extensions have been added to support mathematical markup, which result in either PNG graphic output or Javascript-based rendering. The Matplotlib project has its own math extension for Sphinx, which does not require that you have LaTeX installed in order to render images of equations.

So far, Sphinx is a tool created by programmers, for programmers. All of the projects that are listed on the Sphinx site as using the tool are Python-based, and all but one of them are oriented towards programmers as users. (The exception is calibre, a tool for managing e-book libraries.) Tech writers are not going to abandon FrameMaker (or even the DITA Open Toolkit) and embrace Sphinx and reST. But Sphinx solves a riddle that has gone unanswered for far too long. It provides a way for programmers to document their libraries, frameworks, and applications in real, book-like documents, and publish them to the web and to PDF from a single plain-text source without obscure syntax or cumbersome toolchains.

For open-source projects, which typically don't have a tech writer involved, that is a mighty fine thing.

Mary Connor has already posted a report on Ragan Haggard's presentation to Austin STC on his experience in writing documentation for OpenDS on a wiki. His slides are available from his wiki profile page.

Overall, it sounds like the project success is mixed.

On the positive side:

• They have professional quality documentation in a wiki.


• The documentation has received contributions from Sun SMEs.

The downsides:

• They have not received significant contributions from external users. I think it may be too early to draw a judgment on this score, as the project is new, with version 1.0 just released in July. It sounds like a community has not yet coalesced around the project.


• They do not have a satisfactory solution for hardcopy output. They are currently using a process that involves wget, sed, and HTMLDOC. Having tried a similar process to convert Doxygen HTML output to PDF, I feel their pain.

Given these downsides, they are looking to convert the OpenDS docs to DocBook (or rather, Sun's version of it) going forward. The current wiki will continue to exist for version 1.0, but future releases will not be documented in a wiki.

In my recent post on FLOSS Manuals, I mentioned that while it's a wiki, it's not a HAT. Now I've come across a wiki that is being promoted as a HAT: Zoho Wiki.

Zoho offers an extensive suite of online productivity, collaboration, and business applications. It appears that only the business tools currently have subscription fees associated with them (but I didn't find this stated explicitly anywhere, which kinda bugs me). Zoho Wiki is in the collaboration category, so it appears to be free (gratis), at least at the moment.

Cherryleaf offers a brief critique of Zoho Wiki's HAT aspirations. Among their criticisms:

With a move to a wiki, the users seem to have lost a table of contents that follows where you are in the document.

I found that this wasn't true—the TOC did track my navigation. But that may be browser-dependent (I use Firefox).

Some of Zoho's 10 Reasons Why Zoho Wiki should be your Help Authoring Tool are not quite that. Item #3, "WYSIWYG Authoring", is really a reason why Zoho Wiki isn't geeky and painful to use; most HATs, if not wikis, already have WYSIWYG editors. Item #7, "No Expertise Needed", seems a bit disingenuous; I have no doubt that really leveraging Zoho Wiki requires a learning curve, just with other HATs, while simply writing content is straightforward in most HATs.

Still, if you're looking for a free/cheap HAT option, especially if you want contributions and collaboration from non-professional writers, Zoho Wiki is worth considering.