- Number of videos:
Writing best practices documentation is definitely an art, but that doesn't mean a little science can't help us along. Through some trial and error, I've uncovered some tenets of writing engaging, readable best practices docs. I'll walk through a bit of my path to discovery as I highlight and give examples of successful and (enthusiastic) reader-approved best practices documents.
Most of our work as technical writers is geared toward persons external to the company (users, customers, consumers, etc.), so our first concern is creating something engaging and useful for them. Some of our tasks and projects, however, require us to consider a more complex audience. At Puppet Labs, the documentation team curates, evaluates and edits internal documents (both inter-team and intra-team) and develops documentation meant to be used by internal employees, with the knowledge that these documents may one day need to become external documents. The team also develops documentation guidelines that are meant to be followed by internal employees and external users. Lauren Rother and Fred Lifton of Puppet Labs will discuss the way in which these tasks complicate the usual notion of audience, and the way in which they approach and manage working on projects that require an eye on the future as well as the present.