HomeRolesContact
Cloud
[Solution Architecture] ๐Ÿ“š Docs-as-Code ๐ŸŽ“
Software Architect
Software Architect
September 26, 2022
2 min

Table Of Contents

01
WHAT is Docs-as-Code
02
WHY We like Docs-as-Code
03
HOW to Create and Manage Quality Documentation
04
Adopting Docs-as-Code: from Hackathon to Production
05
Docs for Agile Delivery in Practice
06
Live Demo: https://solution.job4u.io
[Solution Architecture] ๐Ÿ“š Docs-as-Code ๐ŸŽ“
  • ๐ŸŽฏ The exploration and experimentation of how documents can be transformed into valuable sources of information. ๐Ÿ“š
  • ๐Ÿš€ Live Demo: solution.job4u.io
  • ๐Ÿšง docs.oceansoft.io

WHAT is Docs-as-Code

  • โœ๏ธ Documentation as Code (Docs-as-Code) is a growing trend in software documentation, in which documentation is written using the same tools as code:

    • Issue Trackers, Version Control (Git), Code Reviews: Github
    • Plain Text Markup (Markdown, Asciidoc, reStructuredText): Markdown
    • CI/CD, Automated Tests: AWS Amplify
  • ๐ŸŽ The product team needs to follow the same workflows as the development teams. As a result, both writers and developers feel ownership of documentation and work together to create a valuable source of information:

    • Adopt an โ€œagileโ€ approach to content creation
    • Content is the responsibility of the entire team, not just the technical writers
    • The culture of adapting and improving content and processes over time.

WHY We like Docs-as-Code

In general, Docs-as-Code offers the following benefits for Technical Documentation:

  1. By integrating with the Development Team more effectively, the Release Technical Writer can deliver higher-quality documentation (information architecture, customer experience, etc.) more quickly through collaboration with multiple voices.
  2. Developers often write the first draft of documentation, avoiding the documentation becoming a bottleneck. The writers then define and automate the process, including approval gates, automated quality checks, such as spelling and grammar, and external content publishing, such as https://solution.job4u.io and/or Developer Portal.
  3. New features canโ€™t be merged if they donโ€™t include documentation, which incentivizes developers to document them immediately. Furthermore, Documents-as-Code eliminates the need for proprietary tools for technical writing and publishing.

HOW to Create and Manage Quality Documentation

The above diagram depicts a simple content authoring, review, and publishing workflow:

  1. The documentation is located in the docs folder in the docs branch. We use an IDE like VSCode to create markdown files as well as extensions for diagramming tools like DrawIO, so you can also version control your diagrams!
  2. Authors publish the branch to the GitHub source control system. Technically, they donโ€™t have to do this every time, but itโ€™s good practice as a backup.
  3. Authors create a Pull Request (PR) when they are ready to submit content changes.
  4. Content Editors will receive a notification when a new PR is published. Upon reviewing the content, the Editor can approve or reject the submission; the Editor can add comments so the author knows what must be approved.
  5. Once a PR is created/updated (following feedback), an automated pipeline will execute various quality checks against the content.
  6. Once the editor has approved the PR, the content can be merged into the main branch.
  7. Content from the main branch can be built and deployed automatically to users using AWS Amplify CI/CD (Continuous Integration and Continuous Delivery) Pipeline.

Adopting Docs-as-Code: from Hackathon to Production

Ideally, the architecture document should be prepared in Markdown format and managed in a Git repository to ensure high quality, manageability, version control, and traceability.

We use the following developer tools and processes to create and deliver content:

Docs for Agile Delivery in Practice

  • Installing MkDocs & Material Design theme for MkDocs

    pip install mkdocs mkdocs-material
    mkdocs new docs
    
  • โœ…ย Branding

    • Adding your Logo to Header
    • Adding your Favicon
    • Adding your Social Media links to Footer
    • Adding your Brandโ€™s colors
    • Adding fonts to match your brand

โœ…ย Markdown Extensions

โœ…ย AWS Amplify CI/CD Pipeline

  • amplify.yml
  • Amplify >> Previews
  • Amplify >> Notifications

Live Demo: https://solution.job4u.io

References

  1. Docs Like Code - Anne Gentle
  2. Modern Technical Writing - Andrew Etter
  3. Amazon Web Services (AWS) told the story of their teamโ€™s move to docs as code: what worked, what didnโ€™t, whatโ€™s next.

Software Architect

Software Architect

Solution Architect

Designs, develops, modifies, documents, tests, implements, installs, and supports software applications and systems.

Expertise

Agile
Architect
Cloud

Social Media

oceansoftgithublinkedin

Related Posts

๐Ÿณ End-to-End EKS Blueprint for Terraform
๐Ÿณ End-to-End EKS Blueprint for Terraform
October 25, 2022
1 min

Quick Links

๐ŸŒ About Us๐Ÿ“ธ Youtube๐Ÿ’Œ Contact Us

Social Media