Documentation

Docs as code doesn’t have to mean Markdown and Git

After almost 15 years as a technical writer for software companies, I’m a convert to the docs as code philosophy. But while I like Markdown and Git (I use them for this website), I wouldn’t use them to document enterprise software. I’d miss the benefits of dedicated documentation tools like structured authoring, single sourcing and high quality PDFs to name a few. You may have been told that you have to give up your tools and become more like a developer to do docs-as-code, but I don’t think that’s true.

Read More

Writing American when it's not your first English dialect

When I started out as a writer I used to use Oxford English. That’s the one with the (correct) -ize spellings. Although as a journalist I was told to avoid unnecessary punctuation and so I avoid the Oxford (serial) comma. But when I became a technical writer I found myself using American English in my day job. Eventually I got fed up with switching back and forth and settled on using American English exclusively. In this article I’ll use Colonial to refer to all non-American dialects of English.

Read More