4 ms·
Documentation near code is a good idea, but unfortunately it covers only part of the problem. There is a big portion of documentation that should be available
by smokel 2y ago
Documentation near code is a good idea, but unfortunately it covers only part of the problem.
There is a big portion of documentation that should be available to "other persons", such as architects or project managers, who may not want to visit the codebase.
Another challenge is that for these people, diagrams are typically more useful than text. This still requires some manual effort which is difficult to achieve with Markdown.
- euroderf 2y agoAgreed on all points. Regarding para 2, I am assuming that there is something like a CMS in place that can pluck docfiles from version control and massage them and insert them into an outline/ToC. (And then propagate changes back to version control.) Regarding para 3, there's now many GUI tools for working with Mermaid et al. But are any of them properly integrated into documentation systems ?
- robertlagrant 2y agoArchitects should definitely be visiting the codebase. Why would project managers be updating docs? I'd have thought stuff like docs translations done by translators would be a better candidate for non-code editing.
- mfuzzey 2y agoAgreed with your point of accessibility to people who don't live in the code. But that doesn't preculude documentation near code nor Markdown. It just means that you need a CI job to publish the doc stored in the git repo as (for example) HTML or PDF. For diagrams stuff like PlantUML are great, edit as text, publish as images.
- jeffreygoesto 2y agoCan confirm. We are using Sphinx(-Needs actually) and I can send deeplinks to develop, release or feature branch rendered docs to everyone, including non technical staff. You just have to know the "latest of develop" or release links always work, the branch ones are for quick and ephemeral communication only. We include PlantUML and drawio as source along with the code and PR reviews check that code and doc update in sync.
- spockz 2y agoWe now use MermaidJS to render diagrams from text source in our documentation and that works pretty well!
- ElevenLathe 2y agoI 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/
- consteval 2y ago> who may not want to visit the codebase Personally, I think they should get over it. Git is not a "software dev" program. Version control is crucial to pretty much everyone who touches the product. I think therefore everyone should know how to navigate their codebase and use Git, at least a little. Also, you can use git submodules for your documentation so it's kind of separate from code. The only problem is submodules kind of suck ass, so I don't know if devs would be keen for that.