10. Use Gatsby as a documentation platform

Date: 2019-10-07

Status

Accepted

Context

Confluence has been traditionally used as a company wiki where to store bits of documentation. It tends to get fragmented, incoherent and hard to search on. When creating technical documentation many developers prefer easy Markdown format that can live near code, in the team code repositories. It's already possible to pick up Markdowns and render them in Confluence but it won't help with fragmentation.

Confluence is also impossible to make look like a brand if company wants to publish documentation to wider public like customers, potential employees and 3rd party developers and Confluence is basically always internal and needs authentication.

Decision

This decision implements decision "2. Use automatic document generation".

Gatsby is a static site generator and part of a wider JAMStack architecture style. The idea of movement is to serve static HTML files and accompanying JavaScript via CDN and rely on APIs in a more dynamic content.

Markdown files are committed to code repository as any other code so they will have a natural audit log of changes. After that new version of static site is generated in the CI system when content changes and generated files get uploaded to static file storage, like S3, from where they can be easily served through CDN.

Gatsby as a flexible generator can source both from technical Markdown files and any appropriate headless CMSes o the best appropriate content management tools can be chosen, is it just a code editor or fancier CMS UI in the cloud. Specific content management UI tools like NetlifyCMS and TinaCMS can be also integrated to deal with Markdown files in a more user friendly GUI way.

As an additional big benefit documentation sites can "look" like Valamis and share components with Valamis as both use React, a JavaScript UI library. Also public and authenticated sections can be differentiated by either generating public and private sites as a different entities or adding authentication mechanisms within one site.

Serving only static sites from CDN is also the cheapest way to serve web sites.

Consequences

Developers can place their markdown files in project repositories where they are picked by CI pipeline and static documentation sites get built. Other groups like UX can use headless CMS if markdown is "too technical" and those cloud tools use webhooks to trigger CI's site building.

Markdown is easy to learn so there's not a big hurdle for developers to overcome but company should define proper examples and templates for different styles of documentation.