3 ms·
I recently started keeping docs in Markdown but with a CD job to render them and publish to Confluence. We only have internal users but many of them are non-tec
by ElevenLathe 2y ago
I recently started keeping docs in Markdown but with a CD job to render them and publish to Confluence. We only have internal users but many of them are non-technical. This seems to be a sweet spot -- easy for us to update, but also easy for users to find.
It also opens up the possibility of generating the docs themselves from any data that are available at build time. For example, we have a page with a pretty complex Graphviz visualization that gets built from some of the data files we ship with the product. When the data changes, so do these diagrams. They literally can't get out of sync without us noticing (the build breaks). I see more opportunities for this kind of thing all the time now that I'm looking.
- hinkley 2y agoI don’t know if it’s built in or a plugin but there is a way to embed a markdown document in version control into a confluence page. I don’t recall if it was any markdown page or had to be in bitbucket. I used a simple intro and then embedded the docs from version control for a couple chunks of our architecture. Helped a lot.
- tgrayson 2y agoIf you replace the domain of the raw GitHub file with pointillism.io, it will fetch and render right out of your repo. This removes the CICD requirements and ensures currency. https://pointillism.io/ https://pointillism.io/