Docs

Migrating from Markdown to structured authoring

I’m a huge fan of Markdown. It’s great for wikis and writing content for static sites (most of the content on this site is written using it). But there comes a point in software documentation when the size of the project or the number of contributors has grown to the point that you need to impose some kind of structure on it. And that’s what structured docs are for. One of the main reasons you’d want to do that is to separate the content from the presentation. And that in turn enables you to present the content in different ways on various targets, such as print and online. But you’ve got all this content in Markdown already. So what are your options? You could recreate everything from scratch (don’t do that). Or you could migrate from Markdown to a structured authoring system.

Read More

Creating documentation in XML

If your documentation has reached the limits of what’s possible in Markdown, and you’d prefer not to fall back to HTML, it’s time to consider authoring in XML. And no, I don’t mean using Microsoft Word and saving in .DOCX format. Whichever schema you choose (DITA, DocBook, XHTML or something else), you’ll get the benefits of single sourcing and structured authoring, which will save you time and money, especially if your documentation is translated into other languages.

Read More

Creating documentation in an agile environment

Google for images of agility, and you’ll get dog trials. So let’s go with that analogy. If you create written content for software, going from waterfall to agile can feel like being a dog unexpectedly facing an obstacle course when it’s time for walkies. And instead of once a day, now walkies is every hour. Maybe not the best analogy. I’m not sure what the dog equivalent is for having to throw away all the work you’ve been doing for the last week and start over. Ok, let’s start over.

Read More

Getting started with REST APIs

REST (representational state transfer) APIs (application programming interfaces) have been around since the turn of the century, when they were defined by Dr. Roy Fielding in his doctoral dissertation. Since then, they have become the main method for connecting the components in microservices architectures.

Read More

Revisitng DocBook

The Darwin Information Typing Architecture (DITA) and DocBook are two XML-based authoring frameworks. I strongly prefer DocBook. Today’s article is an update of an article on the subject that I originally wrote for the Spring 2011 issue of Communicator. I may have been on to something because in 2014, a group of DITA specialist gave up consulting to create their own component content management system (CCMS) based on DocBook.

Read More

Using LanguageTool to improve your writing

As I’ve previously remarked, I missed two things on switching from print journalism to technical writing. I covered style guides last week, so this time it’s editors (I retained the black coffee addiction). If you have to write customer-facing copy, and you’re lucky enough to have an editor, make sure their boss knows how important their work is to your job. If not, there are some software solutions that can help.

Read More

Creating a writing style guide

When I switched from journalism to technical writing, the two things I missed the most were style guides and editors. When tech writing departments are downsized, editors are the first to be let go. On three occasions when I was the lone writer in an organization, I created my own style guide from scratch. But even when there is a style guide, it may not be current with modern terminology or language use. If you have to write customer-facing content as part of your job, especially if you didn’t train as a writer, you need a style guide.

Read More