I really wish tech writing would get more respect. I work in medical devices where we have to produce a ton of docs. Instead of hiring writers we burn a lot of engineers’ time writing docs. Their main job is to produce systems and writing is just a side annoyance to them The result is badly written, inconsistent documentation that’s close to useless besides fulfilling regulatory requirements.

The main problem with documentation in my experience is that management just doesn't care.

I've been a tech writer in organizations that are layoff forward or micromanaging and people naturally begin to horde information to try to preserve their jobs (it didn't work.)

But because of that attitude I could also see that it was harder to get new hires up to speed because no one dared share knowledge, which wasted enormous amounts of money. Yet at other organizations that were more open to sharing I was able to reduce training times by 75% because I created a curriculum that worked way better.

I created a wiki for the support team and they were able to reduce call times by 40% because they had a place with the answers to the questions they were tired of answering. I reduced support calls by 60% by expanding the knowledge base to answer common questions, and built trust with customers because they worked.

By asking around what the best configuration was, and there was a lot of contradictory information, QA found ways to make the product perform 42x faster.

But none of that mattered in the end, because management can easily lay off technical writers to boost the stock price, and it takes years to feel the pain, by which time they've moved on already anyway.

There is also the hysteresis issue, they'll bring in a tech writer after a long time and it takes ages to become productive because of all the firefighting that needs to be done first, which is invisible.

WWII was where technical writing was recognized as valuable, but never got a movie, which would have helped provide respect.

Docs-as-code is great an all but that is for talking to other devs and you certainly don't want end users accessing the code. I love Apple for its accessibility but there are just so many features available that finding if the feature even exists can be the challenge, which needs better technical writing just to raise awareness.

Devs as writers are not just expensive, but they are trained to talk to computers asking them to write to another dev is hard enough, learning to write to all the kinds of end users that need the information is a whole other skill set. And it certainly doesn't help that 54% of Americans are functionally literate (reading <6th grade level).

Well, my personal docs, meaning org-mode notes, are actually my infra because using NixOS the OS (config) itself is tangle-ed from notes, like zsh, Emacs config, a custom ISO to deploy etc as long as any other noted things, contacts anniversaries included. BUT that's limited to what I can "document" this way. For instance Firefox behind user.js can't be much "documented".

Long story short the "documental culture" was described in the pioneering days of IT, but it's almost lost, both for the technical aspects (like literate programming) and the human aspects (like the "oral tradition" of most companies)... Even schools do not practice document culture much, how could they be the backbone of our society?

Every time this comes up, I am mystified by why very few programmers I have met are aware of the concept of Literate Programming:

http://literateprogramming.com/

as developed by Dr. Donald Knuth to create the programs TeX and METAFONT.

The big thing here is that writers need different tools than programmers --- but one thing which wasn't acknowledged for TeX was that the woven .web files documented a low level of the programs in question, one which was so low that the woven documentation wasn't really useful to most folks --- arguably, what should have happened is plain.tex and plain.mf should have been plaintex.web and plainmf.web and included the text of _The TeX Book_ and _The METAFONT Book_ respectively (perhaps one day Dr. Knuth will allow that, or take the time to do this).

The mention in this podcast of TypeSpec is interesting, but the proposed application seems a very narrow one.

A better option maybe would be a collaborative approach where it is acknowledged that code which cannot be easily explained/documented maybe needs to be re-written:

https://www.folklore.org/Inside_Macintosh.html

Just watched MIT's OCW for Introductory Python, and one of the suggestions there for debugging was describing the code to a child (or kitten, or stuffed animal) --- of course the best code is that which never needs to be written (using a library), but arguably second-best is the code which is correct and doesn't need to be debugged, so third-best would be code which is documented well enough that it may be debugged/re-written easily.

When I looked for Literate Programming tools for my current project, I didn't find anything which seemed a good fit, so resorted to asking on tex.stackexchange.com https://tex.stackexchange.com/questions/722886/how-to-write-... which allowed me to create:

https://github.com/WillAdams/gcodepreview/blob/main/literati...

which I've been using in:

https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

(which is currently being re-written in Python)

Quite simplistic, but working with the linear .tex file is way better than my previous approach of tiling 3 different files open in 3 different OpenPythonSCAD instances and using a fourth window to test the code. I'd be very interested in suggestions of other tools and resources to consider. I've been collecting LP texts at:

https://www.goodreads.com/review/list/21394355-william-adams...

(in particular, while not an LP text, Ousterhout's _A Philosophy of Software Design_ was quite striking and reading through it and then reviewing my code to apply its principles one chapter at a time helped immeasurably)

The idea that they have here of using AI to make a first automated pass at documentation and then editing it by hand seems like a lot of extra work, and likely to create the possibility of introducing some subtle misunderstanding in the text which is then difficult to ferret out.