Comment by euroderf | Hacker News Reader

Comment by euroderf | Hacker News Reader

Parent Full thread

Having worked both as a developer and as a technical communicator (for software), I'm thinking that low friction for developers is paramount, and that therefore the way to get developers to put some effort into it is to have documents both (a) written in Markdown (or adoc or rST or typst) and (b) co-located with code under version control. Change the code, change the docs, no screwing around, BUT a quick & simple brain dump can suffice because of [see next paragraph].

To whit: I have yet to hear of a documentation system that provides fully bidirectional updates between such documents-as-code and edits made further downstream along the documentation production pipeline. That is to say, when a TC person or a reviewer makes edits to content, these changes should propagate back to the docs-as-code material.

Then everyone benefits, including senior devs whose scarce time is optimised by having TC people expand and polish their hasty scribblings, and junior devs who have well-maintained documentation at-hand in-place.

My 0.02€, YMMV. Maybe too niche.

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.

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.

I 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.

If 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/

Agreed 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.

Can 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.

> 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.

We now use MermaidJS to render diagrams from text source in our documentation and that works pretty well!

Agreed 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 ?

Architects 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.

the second you put docs into version control next to code it's no longer low friction enough. Suddenly you have peer review for docs change is far too much work.

Reply on news.ycombinator.com