Saul Salazar/Corporate Technical Documentation

Created Sun, 21 May 2023 00:00:00 +0000
836 Words
documentation best practices

I realized moments before publishing that this article sounds like Documentation / Docs as Code but you can call it whatever you want :D

Problems

  • How to write technical documents? (at large scale company)
  • How to find information faster? (to increase productivity)
  • How to separate different information? (security purposes)

Solution

Use the same workflow developers already know and love (Git) and write documentation using plain text (Markdown), let the docs be easily written on the favorite editor of anyone.

The markdown files (.md) are perfect for SSG, Static Site Generators, which can create a static website. To help you get started you can use frameworks like Hugo, Jekyll, Next.js and many more.

Big tech companies already are using the Git + Markdown + Hugo combination for technical documentation.

Benefits

  • Developers and Writers can work together.
  • First draft of documentation must be implemented by Devs.
  • Use the same tools to review code and documentation changes.
  • You can block git merge if they dont finish documentation, to incentive writing while they are fresh.

Tools

The tool named Hugo is a widely used SSG (Static Site Generator) and even Google maintains the Docsy theme to provide a quick start for technical documentation.

Docsy supports local search with Lunr, a Javascript-based search option that lets you index your site and make it searchable without the need for external services. This is a good option particularly for non-public sites.

For the CI/CD pipeline you can add even linters, for example If you want to implement an style guide you can use vale.sh. It is used by a lot of companies like Microsoft, SAP, Docker, GitHub, etc.

Pandoc is optional but it can be used to convert markdown to many different formats.

Benefits

  • Universal
  • Ultra Fast
  • Multilanguage
  • Works Offline & Private Networks
  • Formatted Data (YML, JSON, TOML)
  • Drafts and Git Branches (Collaboration)
  • Supports Diagrams (Mermaid, UML, MindMap)
  • Automated permissions sync via GitLab / GitHub

Why: Text Editor + Git

Well, I think it’s because a software engineer communicates through code and almost any developer already writes technical documentation using Markdown, almost each Git repository has the README.md file and some the docs folder.

Also we already got the infrastructure, technologies and best practices with everything related to Git like CI/CD, Linting, Access Control, Bots, Code Reviews, lets boost our already trusted tech stack using Hugo and Pandoc.

Why: Universal

  • Websites (html)
  • Documents (pdf, mobi, epub)
  • Presentations (pdf, powerpoint, reveal.js)
  • Offline Wiki (zim wiki)
  • Linux Manual Pages (man command)
  • Jupyter Notebooks

Why: End Users

  • 1st Class: Developers (Engineering Department)
  • 2nd Class: Developers (Data Science Department)
  • 3rd Class: Managers (Administration Department)

Scenario: On Call

  • We will login to sourcegraph
  • Search the keywords or string across all repos
  • Find the docs and code really fast in the same app

Scenario: Finding Info

  1. Reading websites
    • area-tech.docs.company.com
    • team-name.docs.company.com
    • group-name.docs.company.com
    • product-name.docs.company.com
    • component-name.docs.company.com
  2. Reading online repo (markdown files)
  3. Reading offline repo (VS Code)

Scenario: Writing Info

  • EASY: If you are seeing a website, it will include a link that says “Edit this page”
  • Else, go to your organization repository list and search for “docs”
    • Select the repository of your team/service/product/area
    • Search using the page title or go to the section you want to edit content/$category/$subcategory
    • Select the file you want to edit
    • git commit & git push
    • Automatically deployed (in multiple formats)

Architecture

  • Standard (DNS, Web Hosting, CI/CD pipeline, themes, categories & tags)
  • Tutorial (how to guides, example repos)
  • GitLab Groups
    • /docs/teams/team-example
    • /docs/services/service-example
    • /docs/products/product-example
    • /docs/groups/group-example

DNS

  • Convention
    • ${type}-${name}.docs.your-organization.com
    • type can be team, service, product, group, area
    • name is the name of the thing you want to document.
  • Record: *.docs.your-organization.com

Hosting (static files)

  • GitLab Pages
  • GitHub Pages
  • Netlify
  • Any CDN
  • Self Hosted
    • Any Web Server (nginx, apache, litespeed)
    • As containers with an automated proxy with SSL

CI/CD Pipelines

  • Docs Standard
  • Docs Notifications
  • Docs Extra Formats
  • Docs Sync to GDrive

Content Organization

  • In Order
    • Site Hierarchy
    • Categories
    • Tags
  • Categories are used for broad grouping of post topics.
  • Tags are generally used to describe your post in more detail.

Site Hierarchy

Site Hierarchy Example

  1. Overview
  2. Getting Started (Onboarding, Offboarding)
  3. Strategies
  4. Projects
  5. Services
  6. Random
  7. Deployment (terraform, ansible, aws-cloudformation)
  8. Compute (virtual-machines, containers, functions)
  9. Networking (dns, load-balancers, vpc)
  10. Databases (mysql, mongodb, postgres)
  11. Storage (object-s3, object-glacier, block-ebs, file-efs)
  12. Monitoring (prometheus, grafana)
  13. Security (iam)
  14. Notifications (email, http)
  15. Message Queues (rabbitmq, kafka)
  16. Shared Services (gitlab-ci)

Tools (Open Source)

  • Git
  • Markdown
  • SSG (Static Site Generator)
    • Hugo with the Docsy.dev theme made at Google
  • Exporter (Convert Markdown)
    • Pandoc

Optional CMS (GUI)

Development Practices

Who Uses Hugo

Who Uses Netlify

Others Solutions

  • Atlassian Confluence
  • Google Sites
  • Google Drive
  • Google Notes
  • Propietary Vendors

Other Solutions Bad Side

  • Pricing
  • Vendor Lock In
  • No Backups
  • No Style Customizations
  • No Offline Support
  • Slow search engine (stored in shared database)
  • Another step for onboarding / offboarding process