Publish frequently - Basics

Modern technical writing - Andrew Etter 2016

Publish frequently
Basics

Publishing should not be a special event. It should not be challenging. It shouldn't require anything more than a quick sanity check and a glance at the build log. Something about your process is broken if you need more than a minute to verify that content is ready to post to a production website.

Many ways of catching problems exist. For large, complex help systems, you can use a continuous integration system to run a series of build tests after every commit or merge. This method is likely overkill for most help systems, where the testing should occur manually during the review process. Reviewing contributions to the documentation is more complex than just asking, "Is this content accurate? Is the writing well-organized?" It also means building the finished product and ensuring that the change has not introduced any new errors or warnings.

Even simple automation is effective, like a Cron job that checks out and builds the documentation every hour, writes the build log, and posts the resultant content to an internal staging server. Unlike software development, the process doesn't need to be especially elegant or sophisticated, just simple and functional.

1. Regarding creative writing: entertaining people is useful, too.↩

2. Not always the best assumption if your writing appears online.↩

3. I'm not actually going to cover the process, because for a morning ritual, it's embarrassingly complicated.↩

4. One that isn't detailed enough to contain any critical bugs.↩

5. Your job is in jeopardy if you don't.↩