Why Documentation
A Library is a collection of different types of media, housed and organized for consumption in the quest for knowledge and learning. They are typically staffed by people who identify, acquire, classify and organize information of interest from different sources for the benefit of those seeking to gain knowledge.
The word library is derived from the Latin words liber (a book or document) contained in a libraria (a collection of books), and librarium (a container of books).
The gathering of knowledge started with the Sumerians who documented on clay tablets using a complex system of writing called cuneiform dating back to 2600 BC, a more basic form existed dating back some 3400 to 3500 BC.
The Great Library of Alexandria was one of the largest and most significant libraries of the ancient world. How many scrolls and text it housed is unknown, but it was estimated to be anywhere from 40,000 to 400,000 at it's peak.
Because of its vast collection, Alexandria was known to be the capital of knowledge and learning with many important and influential scholars actually working in the library.
The decline of the library began with the purging of intellectuals from Alexandria in 145 BC under the reign of Ptolemy VIII Physcon, and the burning by Julius Caesar in 48 BC with a slow decline over time until its eventual end.
This opening post is not here to serve as a history lesson but to introduce us to the idea of how, through the housing of information that is made available to others, we can greatly improve, as well as ensure the survivability and accessibility of knowledge and learning, be it for public consumption or to ensure business continuity, and to highlight how easy it is to loose important knowledge that is critical to future generations when the people that had the knowledge are not around anymore.
Having good documentation is essential to having a stong educated society, good business and employee experiences as well as to ensure that you are passing knowledge on to the next generation of people that will replace you in the future. Writing them however, can seem overwhelming and difficult to implement and maintain as the information needed to support our documentation, as well as the audience relying on them keep changing and growing more diverse.
Documentation creates the first impression our visitors, students, customers and peers have about us, our products and the services we offer; and nobody likes poorly written documentation. Imagine trying to build a Lego set for your child, or, trying to install new brakes on your car but the instructions are either not clear enough or have pieces missing all together.
Well written documentation that caters to everyone is better for inclusivity as it allows us to better support our peers regardless of their age or technical capabilities. Keep in mind that your writings will reach people of all cultures, geography locations, education levels, ages and languages, they will also need to cater for many different disciplines.
These factor all add to the complexity of writing great documentation.
Solving Problems
Good documentation solves problems, you should start your documentation projects by asking why do you need documentation and how can you solve for those needs. Some good ideas are:
- Business Continuity: The last things you need is for catastrophe to hit your business and your employees are not able to find the information or person they need to quickly resolve the issues.
- New-Hire On-boarding: Having good documentation allows seasoned employees to focus on important work while new hires self onboard at their pace.
- Knowledge Retention: What happens when employees leave and they take the knowledge of your platforms with them?
- Social Good: What use is having great knowledge if you do not share it with others and pass it on to future generations. Think of how you learnt the things you know today.
Best Practice
To address concerns, we should use use the following methods when creating documentation, you can mix and match them as needed.
- Consistency: Creating Documentation in a standardized way sets expectations of both creators and readers.
- Language and Tone: Using proper language and tone shows we care about our readers.
- Multimedia: It's not about how many words we write but how best we convey our message and educate our readers by using different media types.
- Charts: Present your data visually, have good charts can help you readers visualize what they need to know.
- Inclusivity: Culmination of all the above, it ensures we are being inclusive of our readers needs.
Documentation Types
Documentation serves multiple conflicting masters as it explains the same thing in multiple ways. Here are a few types of documentation you should be including in you projects.
- Tutorials: Introductions to your projects, these should be short and quick, allowing readers to experience success within 30 minutes.
- Topic Guides: Detailed explanations of why, these foster understanding and should not walk readers through a step by step process.
- References: Comprehensive information on all critical pieces of your product/platforms.
- Troubleshooting / FAQs: Answers to questions for when readers/customers get stuck and you would need to provide help. These should be a living documents.
- SOPs: These provide detailed step by step guidance on how to do something.