Teams have a tendency to develop a lot of bad habits when it comes to documentation. Either a team needs more documentation, or they need less. The Agile Manifesto explicitly states that teams should value working on software over documentation. Thus, teams often conclude incorrectly that documentation isn’t essential or required. Today, we’ll dig into some best practices for documentation to determine how much you'll really need.
But first, it is important to imagine the current state of technology when the manifesto was written. In 2001, over 20 years ago, the world was still very much paper-based. Of course, there were computers and computer systems, but unlike today, many businesses were run on paper. (Reams and reams of paper...)
Now, everything is on the internet, including documentation. This changes the dynamics of documentation, BUT many of the same pitfalls still exist with documentation today as they did when everything was paper-based.
Definitions:
Documentation: Documentation in computer systems refers to written or electronic materials that provide detailed information about the system, its use, development, and maintenance. It includes user manuals, technical guides, system descriptions, API documentation, troubleshooting guides, and legal information for different audiences like end-users, developers, and administrators. The purpose is to facilitate the system’s understanding, operation, and maintenance.
Going from Suck to Awesome
Sucks – Having no documentation at all.
Still sucks – Having out-of-date documentation.
Sucks a little less – Having partial documentation but team members and consumers are searching for documentation that doesn’t exist.
Awesome – Very concise and easy-to-understand documentation, frequently used by the team and consumers. That is, understanding and using the best practices for documentation.
The Best Practices for Documentation
Good Reasons for Documentation
Here are some of the many good reasons for documentation. There are more, of course. So, it is important to explicitly identify what type of documentation your team will create and plan accordingly.
Complex Flows and Rules: If a complex process or set of rules is hard to understand, diagrams can help immensely. I once led several teams, and we had just moved to a third-party e-commerce platform. The shipping price calculation was so complicated I could never remember the rules, even though I helped select the vendors and configure the systems. After creating a simple diagram, we used the documentation in every conversation about shipping.
Legal & Insurance: Depending on the industry, specific documentation may be required as the laws mandate. Incorrect or missing documentation could lead to significant fees and fines. Similarly, insurance required in many sectors will dictate specific documentation. Given the consequences of this type of documentation, I would suggest tracking the creation and status of the documentation with user stories. Stories should be planned and tracked with the same tools the rest of the team uses to build the system.
Employee Onboarding: Fast-growing startups and enterprises need to onboard new employees efficiently. Some essential system documentation can help new team members become familiar with the systems they will be working on.
Checklists: This may be the simplest and most effective type of documentation. Checklists are easy to create and easy to consume. Almost anyone can create checklists. More importantly, they are easy to maintain. Every team could benefit from a set of checklists.
Bad Reasons for Documentation
There are also some terrible reasons to write documentation. Here are some common ones I've come across:
You always have: Documentation takes time to create and even more time to keep up to date, so if the documentation isn’t being used, it is probably a waste of time. Creating documentation should be prioritized and estimated with other team efforts.
Somebody asked you to: First, why they need the documentation and the goal of the documentation. It would be great to have every form of high-quality documentation, but few teams have the resources for such an effort.
A competitor has lots of documentation: Don’t assume the competitor had a good reason to create their documentation. A competitor’s documentation can be an inspiration, but it can also be a drain on your resources to mimic larger and better-funded companies.
Issues with Documentation
Several issues plague documentation. Enumerating them will help your company avoid falling into the same trap.
Out-of-Date Documents: Documentation is a commitment. It should be released in parallel with system updates. Out-of-date documentation can be harmful.
Not Written for the Correct Audience: Documentation should be written with the consumer in mind. The documentation for a consumer good should be written in a non-technical voice compared to the documentation written for a technical expert, which should contain as many technical details as possible.
Types of Documentation
Not all systems will require all forms of documentation. Additionally, not all teams will have the resources to write every type of documentation. Even if certain types of documentation are created, they don’t necessarily have to be to the same level of detail.
System Documentation: This provides a detailed account of the inner workings and architecture of the system. It’s meant for system developers and maintenance engineers, detailing the code, APIs, and other technical aspects.
User Documentation: Tailored for end-users, this documentation explains how to use the system or software, often including tutorials, user manuals, and FAQs. It’s designed to be easy to understand, even for those with a technical background.
Operational Documentation: This is for those who operate the system daily. It includes runbooks, maintenance guides, and standard operating procedures. It’s practical and focused on routine tasks and troubleshooting.
Installation Documentation: This includes step-by-step guides for installing and configuring the system. It is crucial for initial setup and is often used by system administrators. This should be minimal for most systems, but there are complex systems, especially those that live behind firewalls, that may require detailed step-by-step instructions.
API Documentation: For systems offering APIs, this documentation details how to interact with the system programmatically, explaining the functions, classes, return types, and exceptions.
Release Notes/Change Log: These documents provide information about the specific changes in each system version, including new features, bug fixes, and known issues. Tracking changes is essential if common behaviors will change. For example, relational database behavior changes can have significant impacts, especially if they change how data is returned. Another example is the discontinuing support for specific commands or functions in programming languages.
Legal Documentation: This includes terms of service, privacy policies, and licensing agreements. Users need to understand their legal rights and obligations regarding the use of the software.
Troubleshooting/Support Documentation: Designed to help users and IT professionals solve everyday problems, this can include troubleshooting guides, FAQs, and support forums.
Training Manuals/Guides: These are used for educational purposes, providing structured learning materials for new users or training on advanced features of the system.
Test Cases: Test cases can be considered an indirect form of documentation, but depending on how sophisticated your testing framework is, it may be the best place for the development team to determine what features are supported and how they should behave.
Code Comments: Annotating code was initially designed to assist developers in understanding different aspects of the code, but now annotation can be used to create documentation directly. Several tools (outside the scope of this blog) will automatically generate documentation from code comments.
User Stories: Development tasks require a certain amount of documentation to build the system. User stories can be a treasure trove of information. Additionally, many teams now record all their tasks, so there is a rich history. Soon, AI will train on User Stories to generate valuable insights and usable information.
Best Practices for Documentation
The best documentation one of my teams ever produced was for an extensive enterprise system. We were fortunate enough to have the person writing the documentation be part of our team throughout the project. Not only was that person a good writer, but they also understood the technical details enough to translate some very complex concepts into easily understandable content.
Each team will have different constraints, but in our case, we accomplished our work because:
It was written for the audience that was going to consume it. That is, the team identified who would be using the software and tailored the content toward them.
It was easy to understand. The person writing the documentation was a professional. They had the required writing and domain knowledge to create the documentation.
It was well organized. The documentation was laid out in a way that made sense to the consumer. It was structured and searchable.
It was completed at the same time the system was released. The documentation was written throughout the project, so it wasn’t an afterthought. Of course, we had to wait until the product was finished, but we didn’t need to rush the final output, which contributed to its high quality. Even though the documentation is over a decade old, it would still be considered high-quality today.
It was accurate. The writer had direct access to the technical team to confirm technical details. Additionally, the writer had direct access to the software to verify functionality and features. The technical team participated in reviewing the content as it was written.
Documentation today can now be interactive and incorporate community feedback. Overall, there are several best practices, including:
Clarity and Conciseness: Use clear, straightforward language. Avoid jargon and technical terms unless necessary. Always explain them when used. Keep the documentation concise, focusing on essential information. Don’t write documentation for documentation’s sake!
Audience Awareness: Tailor the content to your target audience’s knowledge level and needs. For instance, user documentation should be understandable to non-technical users, while system documentation can be more technical.
Consistent Formatting and Style: Use a consistent format and style throughout the documentation. This includes fonts, headings, color schemes, and terminology. Consistency helps make the document more readable and professional.
Use Visuals: Incorporate diagrams, screenshots, flowcharts, and other visual aids to complement and clarify the text. Visuals can often convey information more efficiently than written descriptions.
Regular Updates: Keep the documentation updated with the latest system changes. Outdated documentation can lead to confusion and errors.
Accessibility: Ensure the documentation is easily accessible to those who need it. This can mean making it available online in different formats or ensuring it’s easily navigable.
Comprehensive Indexing and Searchability: Include a detailed table of contents, index, and search functionality to make it easy for users to quickly find the information they need.
Feedback Mechanism: Allow and encourage users to provide feedback on the documentation. This can help identify areas that are unclear or require more detail. Users continually commenting on a particular area of your system may be a clue that the area of your application needs refinement.
Testing and User Validation: Have actual users test the documentation for understandability and completeness. Their insights can help improve the quality and usability of the documentation.
Version Control: Keep track of different versions of the documentation, especially if the system undergoes frequent updates. This helps maintain consistency between the system and its documentation. Not many teams don’t do this, but it can help with the process. Archive documentation that hasn’t been used in a long time.
Step-by-Step Instructions: Wherever applicable, provide step-by-step instructions. This is particularly useful in guides and manuals, making it easier for users to follow.
Links to Additional Resources: Include links to further reading, external resources, or related documents within your documentation for users who want to delve deeper into specific topics.
Additionally, depending on your company or project, the following may be required:
Legal and Compliance Checks: Ensure all legal information and compliance guidelines are accurately represented and updated.
Localization and Internationalization: If your audience is global, consider translating the documentation and localizing content to suit different regions and languages. Remember, localization isn’t just text. Localization should include cultural relevance, date and time formats, currency, number formatting, etc.
Some tactical approaches to keeping documentation up to date include:
Use your tools to track when an article was last referenced.
At some interval, or when you need a break, review the documentation and purge out-of-date information or tag it to be updated.
Schedule one document item to be updated each Sprint. Decomposing the work into smaller chunks keeps the task from being overwhelming.
As the amount of documentation grows within your system, consider tagging documents for quicker retrieval.
Keep re-organizing the information.
Dedicate time when the whole team can get together for a specified period, say 90 minutes, and work as a team to update a single document repository.
Conclusion
In general, the only documentation that should be written is documentation that is going to be consumed unless it is legally required. If a system diagram will be created for an internal team, it is more important that the document be easy to find in the format the team expects vs. being verbose. Being concise and using common terminology will be appreciated.
Conversely, searchability and look and feel may be more appreciated when writing for a different audience, such as the end user.
Consider your audience, be mindful of resources, be concise, use visuals, maximize online capabilities, and make the content as accessible as possible.
Комментарии