Managing a website without documentation is like trying to put together Ikea furniture without the directions--it's just not happening. Often, documentation is overlooked by companies and organizations on a budget, but it is a truly invaluable part of building a new website. Check out some great tips and tricks from our team of technical documenters, and learn how we provide our clients with documentation for their sites.

Write with Efficient Tools
Writing documentation requires generating dummy content, and our earlier post on lorem ipsum generators give you lots of tools for generating placeholder text. However, technical writers also need to create annotated screenshots to accompany the words that they write, as well as repeat the actual technical steps they are documenting. So here are some additional tools we found to be great assets to a documentarian's repertoire:

• Awesome Screenshot - Use to take screenshot of a full webpage with auto-scrolling. Also provides a link to share your screenshot (stored on the cloud).
• Window Resizer - Save pre-configured browser window sizes to capture your responsive design layouts.
• No Scrollbars Please! - Remove the scrollbar from your browser to take a clean screenshot (especially of a webpage requiring scrolling).
• Skitch - Use to capture desktop screenshots and annotation with arrows and text. We use it in combination with the extensions above.
• Firefox Selenium IDE - Automate the repetitive technical steps that you are documenting.

Confluence Macros
If you use Confluence (an Atlassian product for documentation that integrates with JIRA), then check out the following Confluence macros which we find to be extremely useful.

• Code Block - Insert code snippets throughout a page with syntax highlighting
• Excerpt and Excerpt Include - Reuse a part of documentation on multiple pages
• Expand - Initially hide some documentation as a link, which expands to display content upon a click on the link
• Info, Tip, Note, and Warning - Callout important information, such as status of the feature documented and release versions.
• Panel - Add border (like a box) to separate some documentation from the rest
• Table of Contents - Great for the beginning of a tutorial guide or as a sidebar on a long page
• Page Tree - Great on a page that introduces a topic with sub pages

Be Agile with Documentation

If you are agile, your documentation can be too. In a Johnson & Johnson Drupal project, we are providing documentation services as technical writers embedded amongst developers. Because we are integrated as part of their agile development process, we track our work in JIRA, participate in standups and retrospectives, such that documentation is continuously up to date with each sprint. We find that writing in agile iterations is a great way to capture feedback from various parties involved, including product owners, developers, and users in trainings. This way, strong documentation can be produced to maximize support for everyone on the project. Writing technical documentation is easier and more efficient to do in-sprint, while the features being documented are still present in the minds of the developers and product owners.

Find the Voice for Your Audience
Documentation being agile also means that you can adapt your writing voice to best suit your audience. Try to always learn more about your audience as you write documentation throughout the project. So far, this blog post has been written in an informative, technically instructional voice. Now say that our audience wants something lighter, more familiar, and empowering, then perhaps we should adapt our voice to something as follows.

Ask Not What Your Product Can Do For You — Ask What You Can Do With Your Product

When doing technical writing, it's easy to be... well, too technical. Just because you're a "technical writer" doesn't mean you should think of your audience as "technical readers." Your audience consists of people that want to do things. Empower them! Don't drone on and on about how "this product does many things" (yawn), when you can enable your reader by telling them "You can do many things with this product!" Yes, sometimes the product simply "provides," but any opportunity you have to inform the reader of what they can do, instead of telling them what the product does, take it.

• Boring: "From the dropdown menu, a number of items are available. Selecting one will customize this feature."
• Empowering: "By clicking the dropdown menu, you will see a number of items available to you for customizing this feature. Choose the option that best embodies the spirit of your brand."

Much better, right? The first example, while technically sufficient, does little to engage the reader, and does the bare minimum to inform them of what needs to be done. The second example puts them in charge of driving the product, and uses "you" to communicate directly to them. Also, the second sentence of the empowering example informs the reader of what their motivating reason behind making their choice is. Don't just tell your readers how to do things; let them why they're doing things and what it can do for them and/or their business.
Every website is different, so technical writing should be flexible, adaptive, and leverage the best tools to complete documentation for its team.
Want to learn more about about documentation? Check out our Training & Documentation page.

Terms:

• Drupal Planet
• documentation
• Drupal

Related Services

Training

Get the most out of your education. Learn Drupal in an immersive, hands-on, fun environment. 

Read more