Steps Towards Valuable Technical Documentation

@July 31, 2023

Have you ever noticed what satisfaction there is in working with products whose functionality is to the point and well-documented, written in a professional way along with drawings, and examples to underscore what is explained?

How does your API documentation look? Do you have any and is generated from code and comes with example snippets, application notes, ready to use example projects and use-cases etc? At bitcreed, we take great pride in ensuring customer satisfaction. In this blog we detail our approach to technical documentation of user manuals, code any sort of technical product description.

Less is More

Despite the formal process described here, a 200+ page manual is rarely the desired result for an engineer looking at how to use a simple code-function. Our philosophy is that less is more. We thus try hard to condense the information as much as possible for your target user. This has multiple benefits:

• ensures that changing documentation doesn’t become an added-chore to your engineers
• helps reducing inconsistent information
• information is easier to retain
• no endless scrolling before reaching the relevant information

Our Approach to Technical Documentation

This is our industry-proven approach to improving technical documentation, no matter what state of your product and project is currently in. Needless to say that the process is adaptable to your individual needs.

1. Determine the scope of the product to be documented: To kick off the documentation process, we first determine the scope of the product and review the state of existing documentation. This gives us a clearer understanding of what the product looks like and how users would engage with it.
2. Work top-down to review existing documentation and code: We’ll make sure to understand what package is already available before we start on the deliverables. Those are the steps to build up our understanding:
1. Review applicable user documentation, tutorials in written form, or video: We examine any existing documentation and guides to identify gaps or areas that require further improvement. This review ensures our comprehensive overview of the product's features and functionalities.
2. Review existing architecture documentation: Understanding the product's architecture is essential for creating coherent and meaningful technical documentation. If available, we analyze existing architectural documentation to establish a solid foundation for our writing. Architecture documents jump start the process of the intrinsic process of understanding the product’s inner workings and are a great and valuable resource. If you don’t have them yet, don’t worry as we’ll gladly complement them with whatever knowledge we have gained in the process.
3. Review the public APIs, developer documentation, and source code pertaining to the API: Incorporating a thorough review of APIs, developer documentation, and source code enables us to provide detailed and accurate explanations. We may refer to code-history in repositories or release bundles to highlight version-specific differences or upgrade/downgrade paths.
4. Evaluate the clarity, consistency and coherence of naming conventions: Clear and consistent naming conventions are crucial for ensuring user-friendliness and maintainability. We assess the naming conventions, ensuring they align with best practices and will strongly consider preserving legacy terms as changing naming conventions of already released products may prove to be a stumbling block to your already existing user base. If you do decide that a change is indeed the way forward, we’ll provide guidance on ensuing the smoothest possible transition to your existing users.
3. Write a broad outline for a structure to present the whole package intuitively: Before diving into the documentation creation process, we develop a broad outline that aligns with the target audience's needs. This intuitive structure ensures the information is presented in a logical and accessible manner.
4. Expand the existing, or restart based on our proposal This is the step where the actual documentation is created, architecture diagrams are drawn and snippets are collected into a user-friendly package describe the bells and whistles of your product or solution.

Based on our assessment of existing documentation, we discuss whether to enhance the current documentation or start fresh. This decision is tailored to your specific needs based on your project, team and users.

5. Technical translation: If required, we provide technical translation services, either in-house or through external partners. Our experience has taught us the importance of domain-specific language to ensure accurate and effective translations.
6. Publication: Once the documentation is finalized, we release the comprehensive documentation package to you, to provide your users with the seamless experience they deserve for your quality product. This is also where we pay attention to mark old documentation as deprecated and point towards the new versions.
7. Suggest next steps: Throughout the process, we collaborate closely with our your experts (developers, product owners or other key people/stakeholders), seeking clarification and providing feedback. We also make suggestions to optimize the documentation, such as:
1. Automation: We propose a unified format for inline documentation that supports automatic generation, streamlining future updates. This could include Markdown documents, markers in the source code and/or LaTeX-based templates suitable for PDF or website publication. As we’re also engineers, we’re delighted help implement process automation into your existing CI/CD systems and pipelines.
2. Define additional materials We identify opportunities to enrich the documentation with additional examples, tutorials, videos, and search engine optimization (SEO), etc. to enhance user understanding and discoverability.
3. Ensure proper change-notifications Provide a way for your users to be notified of upcoming API changes, new features, etc.

We recommend ways of notifying your user base about critical updates, changes to APIs, new features, and enhancements. This fosters stronger user/community engagement and adoption of your products.

Other Benefits of solid Technical Documentation

A well-structured and comprehensive technical documentation significantly contributes to improved project maintainability. By following our approach, bitcreed ensures that clients' products are not only functionally exceptional but also thoroughly documented, offering users a delightful experience from start to finish.

Other than the customer’s satisfaction, you’ll notice that the investment into technical documentation is well worth the cost as other benefits emerge: On-boarding of new team members becomes less resource intensive, engineers can resort to diagrams when pondering new approaches during the ongoing development and with available documentation, there’s generally a more clean work-environment available that fosters quality as the product develops.