docToolRec.adoc

DevOps Approach to Documentation

---

2023-05-14 13:48:53 Draft documentation tool option comparisons

I. Introduction

TBD

II. Requirements

What features of Confluence are used in our wiki content? Are there counterparts in the other options under consideration?

Specific Requirements

1. A documentation entry system with source files under version control

2. A process that creates a web accessible documentation site from the source repository

3. Triggering site re-publication process on a push to the source repository (CI/CD pipeline)

4. Support for one or more of the available markdown-based languages for document creation

5. Essential features

   1. Tables

   2. Liats, nested lists, bullet or numbered style

   3. Table of contents

   4. Definition lists

   5. Footnotes

   6. Bibliographies

   7. Callouts (e.g. NOTE, WARN…​)

   8. Task list items

   9. Applicable site themes

   10. Support for common diagram styles (via Kroki)

   11. External file includes

   12. Support for user-defined macros

   13. Conditional markup

   14. Host sites on GitHub Pages and GitLab

   15. Support for reader comments

   16. Supports full-text search

   17. Renders typographic entities

   18. Emoji support

III. Example of an end-to-end documentation system

1. Hugo static site builder with Docsy module:

   1. www.docsy.dev/docs/get-started/docsy-as-module/example-site-as-template/

2. Content in Github-flavored Markdown and/or Asciidoc

3. Publish to Github Pages

IV. Reference Materials

• Evolveum documentation site: docs.evolveum.com

• Asciidoc: asciidoc.org

• Markdown: www.markdownguide.org/

• Github Pages: pages.github.com (Auto Re-Publication on commit to repo)