Publishing Pipeline in Software Development
by ClickHelp — professional help authoring tool
Having a structured publishing pipeline is essential for creating and maintaining comprehensive documentation. This process often begins during the development phase and continues through post-release analysis.
Different companies may have varying approaches to documenting code and features. Unfortunately, most companies either do not have a documentation SOP or have one that is not mandatory. However, if you are a tech lead, you have the authority to enforce a standard procedure within your project or team.
This article aims to offer advice on documenting projects. We’ll explore the key components of this pipeline, including version control, Continuous Integration/Continuous Deployment (CI/CD) tools, and automated testing, while also discussing best practices for documentation.
Starting Documentation Early
Writing documentation typically starts as early as the development process. As soon as specific functional requirements are laid out, documentation work can begin. This is the right time to create the first documents because the development team already has a clear vision of the purpose and specifications.
Therefore, at the early stage, the requirements for documentation may look like this:
- High-level requirements of the project: What it does, what it includes, and any limitations.
- Business requirements: Listing use-cases, features, wireframes (if any), and sitemaps (if any). This section will include an overall picture of how the main menu/sub-menu will look and what the main screen flows will be.
- Technical design: This section will include the initial design of the API endpoints, batch jobs (if any), business logic for more complex flows, etc.
- Appendix: This may include documentation from external parties, such as clients or third-party libraries.
The format is flexible, and documents will be revised, updated, and appended as the project continues.
Having the documentation team involved early in the development process can be highly beneficial. If design screens are available, including screenshots will make the documentation more readable by adding visual context. This step ensures the content is accurate and aligns with the software being created.
Additionally, early documentation allows for the identification of potential gaps in functionality or design that need to be addressed. It promotes continuous integration of feedback, leading to a more polished final product. Features documented as they are being implemented allow teams to create a living document that can be updated as the software evolves, enhancing communication between teams.
Document Review Process
Once the initial drafts are complete, the review process is crucial. Timely feedback and approval are essential. The suggested approach is to avoid having the Research and Development (R&D) team write the documentation themselves. Instead, conduct interviews to gather information and then provide a draft for review. This collaborative approach tends to yield better results, as it allows the development team to focus on development but still share their knowledge with the documentation team.
Additionally, having documentation templates and guidelines can streamline the review process. Pre-formatted templates make it easier for reviewers to identify areas where clarification or improvement is needed. Regular review meetings can also foster communication between teams, ensuring that the documentation’s content and purpose are well-understood.
Collaborative software, such as version management systems or document-sharing platforms, also facilitates real-time feedback. Team members can provide input and suggestions directly within the document, automating the review process and saving time.
Prioritizing Documentation
Prioritizing documentation is key. Focus on documenting the most critical aspects for the upcoming release. If time is limited and not all documentation can be completed, it is advisable to postpone non-critical items. However, this should be agreed upon with the product manager and marketing team, as they understand what is most important to users and stakeholders.
To prioritize effectively, a documentation roadmap can be created that aligns with the product release plan. This roadmap will include key milestones and timelines, helping to ensure the timely delivery of essential documentation. Regular reviews with the product manager will help adjust priorities based on evolving project requirements or customer feedback.
Involving customer support and sales personnel during prioritization can provide valuable insights into which areas of documentation are most important to customers. They are more likely to have hands-on experience with customer queries and can offer valuable feedback to improve user-centered documentation.
Publishing and Version Control
Once the documents are finalized and approved, the publishing phase begins. This is done with version control to track changes effectively. Version control ensures that variations are handled appropriately, and previous versions of the documentation can be accessed when needed. Collaboration is made easier by enabling multiple team members to work on documents simultaneously without overwriting each other’s work.
In smaller companies where version control is done manually, challenges can arise with where technical documents are stored-whether on local drives or in online databases. The culture of file management may lead to engineers saving documents with non-descriptive names or in inconsistent locations. Management must ensure that the latest version is used, especially if hundreds of files are revised by different people.
Many companies address these issues by adding a tracking number to each document’s footer. This number includes a project number, sub-project task number, and version number, ensuring traceability for every document.
Version control not only helps track changes but also maintains a history of documentation development, which is helpful for auditing or reviewing earlier versions. Furthermore, branching capabilities in version control systems allow teams to work on different versions of the documentation at the same time-such as planning for future releases while keeping the current version active.
Additionally, automating the publishing process with version control makes workflows smoother. For instance, connecting documentation publishing to CI/CD pipelines ensures that users always have access to the latest version, minimizing the risk of outdated information.
Continuous Integration/Continuous Deployment (CI/CD) Tools
Integrating CI/CD tools into the publishing process can significantly boost efficiency. These tools automate code changes and deployment, synchronizing documentation updates with the current software version. This integration ensures that updated documentation is always available to users without manual effort.
CI/CD tools facilitate an agile documentation process, allowing teams to deploy and update documents quickly. This is especially crucial in high-velocity development environments where new features and updates are rolled out regularly. With automation, teams can focus more on content quality and less on the logistics of publishing.
Moreover, CI/CD tools can be configured to trigger automated testing for document updates. This ensures that any changes to documentation are checked against the software to identify inconsistencies or errors before being published. For example, if a new feature is added to the software, the documentation can be automatically tested to confirm that it accurately reflects the new feature, reducing the risk of misleading or incorrect information being shared.
Automated Testing
Automated testing plays a vital role in quality assurance for both software and documentation. Testing documentation for accuracy against the software ensures that discrepancies are caught early in the development process. This helps ensure that users can rely on valid and up-to-date information, ultimately enhancing their experience.
Automated testing can verify documentation completeness, such as ensuring that all features are documented or that the documentation adheres to specified guidelines. For example, software programs can be designed to check for dead links in documentation, ensuring that all references lead to working pages. This automation not only reduces time but also minimizes human error, leading to higher-quality documentation.
Additionally, automated testing can check that code snippets or examples within the documentation are error-free and align with the current software version. If a code example is included in the documentation, automated testing can ensure that the code runs properly, preventing users from encountering errors.
By preventing issues from arising before they reach production, automated testing contributes to a better product experience.
Post-Publication Analysis
The job does not end once the documentation is published. The main goal is to ensure that the documentation effectively solves the users’ problems. This is why it’s essential to monitor user feedback and track search queries related to the documentation topics over time.
For example, you can analyze user stories such as “I am totally new to the app and want to learn what functionalities are available” or “I am an experienced user and need to…” Tracking this information can reveal areas where users struggle to find what they need or are dissatisfied with specific topics. This ongoing cycle of refinement is crucial. Regular reviews-such as periodic iterations to enhance documentation after a certain period (e.g., N days or months from publication)-ensure that the documentation stays relevant and helpful.
When focusing on regular users during the documentation creation process, Divio’s Grand Unified Theory of Documentation can be applied, which breaks the process down into four blocks:
- Tutorials: Useful for beginners (“I’m new-help!”).
- How-to guides: Help users perform specific procedures (common in IT ops docs).
- Explanations: Help explain the reasoning behind the system, typically related to architecture and design.
- Reference guides: Used for creating API documentation (e.g., Divio Docs).
Post-publication review can involve collecting user feedback through surveys or analyzing analytics to identify the most frequently viewed documentation pages. Based on actual user behavior, teams can build priorities for updates and enhancements. For example, if analytics show that a topic is frequently searched but not often visited, it might indicate that the documentation is poorly indexed.
User feedback can also be gathered via forums or support channels, providing qualitative insights into the documentation experience. Feedback loops help identify pain points and areas for improvement. Timely updates and reviews of the documentation not only improve its quality but also demonstrate a commitment to providing valuable resources to users.
Conclusion
Establishing a robust publishing pipeline for software development requires careful planning and coordination. By adopting early documentation, prioritizing key content, leveraging CI/CD tools, and utilizing automated testing, teams can deliver high-quality documentation that evolves alongside the software.
Additionally, committing to continuous analysis and adjustments keeps the documentation aligned with user needs, ultimately contributing to a better overall product experience. Maintaining this culture of ongoing improvement allows documentation to grow with the software, ensuring user satisfaction and reducing the cost of support.
Good luck with your technical writing!
Author, host and deliver documentation across platforms and devices
