Writing Technical Documentation with Sphinx, Paver, and Cog

I've been working on the Python Module of the Week series since March of 2007. During the course of the project, my article style and tool chain have both evolved. I now have a fairly smooth production process in place, so the mechanics of producing a new post don't get in the way of the actual research and writing. Most of the tools are open source, so I thought I would describe the process I go through and how the tools work together.

Hellmann, Doug. O'Reilly and Associates (2009). Articles>Documentation>Software>Technical Writing

Guidelines for Good Sample Code

Sample code often provides the quickest, clearest way to learn how an SDK works. If you have software engineering experience, then you should already know many principles for writing good code. However, what you may not realize is that some of the good practices that you learned for writing good production code do not apply to writing good sample code. Some techniques, such as comments and clear variable names, apply to both production code and sample code. However, there are good reasons to use hard-coded values in sample code, which should be avoided in production code, and there are good reasons to avoid object-oriented designs when writing sample code.

Gruenbaum, Peter. Prestwood (2009). Articles>Software>SDK>Documentation

Hey Rocky – Watch Me Pull a CMS Out of My HAT    

When companies decide whether or not to adopt a CMS or continue using a HAT, there are many factors to consider. Perlin outlines elements of both CMSs and HATs that could help you determine which is best for your organization.

Perlin, Neil E. Intercom (2009). Articles>Content Management>Documentation>Software

Using Master Pages in RoboHelp 8

Master Pages, a new concept introduced in Adobe RoboHelp 8, intends to provide flexibility in controlling the layout of topics, where in an author may separate the actual content from the layout of the output and may do it from a single place. In Adobe RoboHelp 8, a user may use Master Page as a Layout and Styling canvas where one may put basic HTML elements to be used for Layout purposes.

Adobe (2009). Articles>Documentation>Software>Adobe RoboHelp

Authoring Tools Do Matter

The authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.

O'Keefe, Sarah S. Palimpsest (2009). Articles>Documentation>Technical Writing>Software

Choosing a Help Authoring Tool

Help authoring tools (HATs) are specialized editors and converters to create online technical documentation. Today, many help authoring tools also provide features for single source publishing, which means that you can generate several output formats and versions from one shared text source. While most tools manage to produce different online formats like browser-based help and compiled help very well, only few tools can also produce printed user manuals (or PDF) of professional quality. Big differences also exist between the tools when it comes to translating your projects into foreign languages.

Achtelig, Marc. indoition engineering. Articles>Documentation>Software>Help

Choosing a Screen Capture Tool

Checklist of key criteria for selecting a tool to take screen captures (screenshots / screen dumps). Screen captures are used within all forms of software documentation, such as user manuals, online help files, interactive demos and tutorials, but also for web sites and brochures.

Marc Achtelig. indoition engineering. Articles>Documentation>Software>Screen Captures

Choosing a Screencasting Tool

Checklist of key criteria for selecting a tool to create interactive software demos (so-called screencasts). Software demos are not only used on web sites but increasingly also as standalone tutorials or embedded within online help files and other sorts of software documentation.

Achtelig, Marc. indoition engineering (2009). Articles>Documentation>Software>Screencasting

Marktüberblick Screencasting Tools

Marktüberblick über empfehlenswerte Tools zum Erstellen von Software-Demos (engl. Screencasts). Software-Demos werden nicht nur für Marketing-Zwecke auf Webseiten verwendet, sondern häufig auch als Ergänzung zur Technischen Dokumentation von Software: z.B. als eigenständiges Tutorial oder auch als integrativer Bestandteil einer Online-Hilfe oder sonstiger Software-Dokumentation.

Achtelig, Marc. indoition engineering. (German) Articles>Documentation>Software>Screencasting

To the Man With a Hammer Everything Looks Like a Nail

An engineer at a company once called me and asked me how much it would cost to edit a Service Manual that he had written for a medical device. I asked him to send it to me so that I could give him a quote. When I received it I saw to my amazement and horror that he had written a 200 page manual (including many graphics) in Excel. When I asked him why he didn't use Word, he replied 'I'm an engineer I know how to use Excel, not Word.'

Hurwitz, Charles. Freelance Technical Writing in Israel (2009). Articles>Documentation>Freelance>Software

Writing Great Documentation: What to Write

Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation.

Kaplan-Moss, Jacob. Jacobian (2009). Articles>Documentation>Technical Writing>Software

Why Help Authoring Tools Will Fade 

Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Software>Help