How to easily create documentation

Some undeniable truths about documentation:

• People hate to write it
• People really need it

When someone needs some help, it can consume a lot of resources, especially when a company is continually hiring new people or losing people to other teams or companies.

There are a couple types of documention:

• Simple questions and answers
• More detailed documents

The usual way things are done

Simple questions and answers are done in person or in chat, usually lost forever except to the recipient of a chat who could search their chats.

Write emails containing more detailed information to someone, a group of people, or a mailing list.

Proposed way

• For short questions and answers, create a page on your wiki (e.g. Confluence) for frequently asked questions and quickly add it after providing it to someone in email and chat.
• After sending an email, create a wiki page and paste in the contents of the email, then send out the URL to your team or whoever is asking for the documentation. I mention Confluence because it does a good job of preserving formatting in copy email content to a Confluence page.

The downside to this approach is that if you later add to or modify any of these pages, the recipient does not have the updated information.

Even better

Add a question and answer to your FAQ page on your wiki, then email or message someone with the URL. Their answer will be the last one, but they also benefit from seeing the other answered questions. They can bookmark it and check it periodically and subscribe to the page to hear about updates.

Create a page on your wiki containing the detailed information you normally would have sent in an email, then send out the URL instead. You could also email both the content and the URL, which would be useful since the content will be searchable in your email program.

Scenarios

Your team

Via chat or email, your team probably shares a lot of team-specific information. Create a site to store this information. This could be useful to those not present when the information was exchanged, especially new employees. Also, it’s easy to forget things after 6 months have passed. It’s much easier to visit and search your team web site that’s devoted to useful information than to sift through millions of emails and chats (which may be separate searches) to find the interesting ones. Also, the pages you create may be useful to a wider audience, so you could create a portion of your team site that is accessible to others.

Mailing lists

Sending useful information to a mailing list is an opportunity to create a page. Also, if you come across useful information, email the author and ask if it’s documented. If not, encourage them or document it somewhere yourself.

Existing documentation

There’s a good bit of existing documentation out there, but some of it suffers from being poorly written or out of date. You could contact the author if you find such a page or offer to clean it up and post your own version of the same site or your own site.