• 🎯 The exploration and experimentation of how documents can be transformed into valuable sources of information. 📚
• 🚀 Live Demo: solution.job4u.io
• 👨‍💻 https://oceansoftio.github.io/docs

Source Code: https://github.com/OceanSoftIO/docs.git

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 or https://oceansoftio.github.io/docs.
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:

• Documentation template: VS Code || Intellij

  • [x] Markdown *.md: solution.job4u.io
  • [x] Ascidoc: github.com/OceanSoftIO/docs/asciidoc
  • [ ] Restructured Text *.rst

• Developer-based workflows: GitHub || GitLab

  • [x] Version Control using tools, such as Git
  • [x] Change control driven though bugs and feature requests tickets
  • [x] Content reviews and merges

• Static Site Generators (SSG)

  • [x] Mkdocs --> https://solution.job4u.io
  • [x] Hugo --> https://terraform.job4u.io/ || https://cdk.job4u.io/
  • [ ] [Jekyll](jekyllrb.com
  • [ ] Docusaurus
  • [ ] Sphinx (reStructuredText)
  • [ ] Middleman

• CI/CD Pipeline:

  • [x] AWS Amplify
  • [x] GitHub Actions: https://oceansoftio.github.io/docs
  • [ ] GitLab Pipeline
  • [ ] Netlify

• Script-Based Design Tools & Architecture Templates

  • [x] Mermaid (UML): mermaid-js.github.io/mermaid/#
  • [ ] PlantUML (UML, C4, Mindmap) : plantuml.com
  • [ ] Structurizr (C4) : structurizr.com

Docs for Agile Delivery in Practice

• [x] Installing MkDocs & Material Design theme for MkDocs

  pip install mkdocs mkdocs-material
  mkdocs new docs
  # ~/Library/Python/3.9/bin/mkdocs new docs
  

• ✅ Branding

  • [x] Adding your Logo to Header
  • [x] Adding your Favicon
  • [x] Adding your Social Media links to Footer
  • [x] Adding your Brand's colors
  • [ ] Adding fonts to match your brand

✅ Markdown Extensions

• [x] https://oceansoftio.github.io/docs/mkdocs-alternatives

✅ AWS Amplify CI/CD Pipeline

• [x] amplify.yml
• [x] Amplify >> Previews
• [x] Amplify >> Notifications

Live Demo:

MkDocs

⚡ You can create an online workshop in one minute using this open-source Jamstack Static Site Generator (SSG) Template ⏱️

```
git clone https://github.com/OceanSoftIO/docs
cd mkdocs

mkdocs serve
```

✅ solution.job4u.io

🔗 https://github.com/OceanSoftIO/docs/tree/main/mkdocs

Hugo

```
git clone -b hugo https://github.com/OceanSoftIO/docs
cd docs/hugo
git submodule init && git submodule update --checkout --recursive

hugo server --port 8080
```

🔗 localhost:8080

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.