Skip to content

Document As Code

Get Started 1️⃣

There are many tools to write documentation, most of them center around writing markdown files which eventually gets converted to HTML pages

Some of the famous ones are

Why Document As Code 2️⃣

  1. Since it is just markdown you don't have to worry about another decommission and later migration
  2. It follows the organization principle of reveal by policy and hide by intension when it comes to Documentation, it encourages learning and sharing
  3. It resides In Version Control System along with your code in a separate project
  4. Out of the box searching available
  5. If you love code, you would definitely love writing documents as code
  6. Highly customizable, lots of extensions
  7. Highly configurable, change themes easily and on the fly
  8. Lots of plugins available
  9. Easily create diagrams
  10. Easily embed other complicated shared html pages
  11. Full History maintained in VCS (github) who changed what and when?

Pain Points 3️⃣

  1. If you don't like to code, you may not like document as code, we will have to wait for sophisticated editors
  2. It would take some time to reflect the changes on your site, even if you have the pipeline setup.
  3. It requires some intelligence to get started. Not that intuitive as Confluence

Comparing 4️⃣

Teams

TODO

Sharepoint

TODO

Mark down websites 5️⃣