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.
We should pivot the culture to one that is pro-liberal arts again. These people know how to read and write better than STEMs in general.
CS as the only path to programming was always too narrow, and often people with a broader education are better at creative solutions. With AI-assisted programming I'd argue they have an even clearer advantage now.
In theory, it isn't that difficult, in practice writing _accessible_ text takes a lot of practice and feedback. Letting go of your own biases towards base levels (curse of knowledge) is something that already trips most people and what people find really difficult to overcome.
Which is why the statement you are responding to is often more true than you might realize. Because these people have had a lot more practice in that specific area. Although not all of them, that would be a generalization in itself.
I’ve always noticed that truly excellent programmers with strong lexical instincts also tend to be formidable with their native language. Not necessarily verbose, but capable of clear and structured writing.
I’d even go so far as to argue that if someone has poor writing skills in their native language, they’re probably not a very good programmer.
From what I've heard from tech writers, it's a job that very few people want to do for a long time, or make a career of it. You get someone for a year or two at most, and then they move on to something more interesting, is the impression I have.
A lot of companies pay and treat tech writers like shit.
If you're a decent tech writer who can write well, grok engineer speak, collaborate well with engineers during crunch time before a release, and apply your technical knowledge to build and maintain documentation infrastructure... well, you'll get comped slightly beneath the level of a developer with similar experience.
For folks like me who enjoy the writing side of things, it's worth it. But there are very few people who truly appreciate both the writing and the development side of the role. You honestly need both.
Most companies pay poorly, and wind up hiring non-technical folks who can barely manage a CMS. Those people can be helpful in a larger org, but at the end of the day, most technical orgs need a truly technical writer who can talk with the engineers directly and mess around with the product pre-release.
Great tech writers have the skills needed to actually do software development or project management, and often end up either moving into one of those or going to more creative writing endeavors.
This has been my experience as well. The best technical writers often know much about the domain they work in, and can do a fair portion of the work themselves (in software engineering, the best technical writers are the ones coding their own writing tooling)
In fact, many fields actually require their technical writers to have some amount of education in the field (e.g. biology BAs minimum or such for medical technical writing).
Unfortunately, this is a braid field in which other technical writers are performing really basic tasks, like writing straightforward gui instructions. I think this wide range gives the market an excuse to undervalue the discipline, while many writers doing important conceptual writing work are some of the most valuable participants in the arena. After all, nearly all of human epistemic and technological development has been conveyed through the medium of text. What are mathematicians if not amazing technical communicators?
This would seem to be a sign that some changes are needed to make it into a career people actually want to do. Perhaps it's at simple as paying more, though probably other changes in workflow/working conditions/status (all correlated with pay) are what would really help the most.
No one gets promoted for good documentation. It just has to be good enough for the promo panel to skim through and be impressed, lots of nice large percent results too. But not good enough for a system to be maintained, or an on-call to work on, or someone new to contribute to.
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:
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:
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:
(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.
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.
We should pivot the culture to one that is pro-liberal arts again. These people know how to read and write better than STEMs in general.
CS as the only path to programming was always too narrow, and often people with a broader education are better at creative solutions. With AI-assisted programming I'd argue they have an even clearer advantage now.
> These people know how to read and write better than STEMs in general
That is completely untrue. Efficient, creative writing is a skill that can be learned by anyone by following a handful of rules.
In theory, it isn't that difficult, in practice writing _accessible_ text takes a lot of practice and feedback. Letting go of your own biases towards base levels (curse of knowledge) is something that already trips most people and what people find really difficult to overcome.
Which is why the statement you are responding to is often more true than you might realize. Because these people have had a lot more practice in that specific area. Although not all of them, that would be a generalization in itself.
I have a liberal arts degree and I don't want to do technical writing. It's so much harder than dev work and it's utterly mind numbing.
I’ve always noticed that truly excellent programmers with strong lexical instincts also tend to be formidable with their native language. Not necessarily verbose, but capable of clear and structured writing.
I’d even go so far as to argue that if someone has poor writing skills in their native language, they’re probably not a very good programmer.
From what I've heard from tech writers, it's a job that very few people want to do for a long time, or make a career of it. You get someone for a year or two at most, and then they move on to something more interesting, is the impression I have.
A lot of companies pay and treat tech writers like shit.
If you're a decent tech writer who can write well, grok engineer speak, collaborate well with engineers during crunch time before a release, and apply your technical knowledge to build and maintain documentation infrastructure... well, you'll get comped slightly beneath the level of a developer with similar experience.
For folks like me who enjoy the writing side of things, it's worth it. But there are very few people who truly appreciate both the writing and the development side of the role. You honestly need both.
Most companies pay poorly, and wind up hiring non-technical folks who can barely manage a CMS. Those people can be helpful in a larger org, but at the end of the day, most technical orgs need a truly technical writer who can talk with the engineers directly and mess around with the product pre-release.
Great tech writers have the skills needed to actually do software development or project management, and often end up either moving into one of those or going to more creative writing endeavors.
This has been my experience as well. The best technical writers often know much about the domain they work in, and can do a fair portion of the work themselves (in software engineering, the best technical writers are the ones coding their own writing tooling)
In fact, many fields actually require their technical writers to have some amount of education in the field (e.g. biology BAs minimum or such for medical technical writing).
Unfortunately, this is a braid field in which other technical writers are performing really basic tasks, like writing straightforward gui instructions. I think this wide range gives the market an excuse to undervalue the discipline, while many writers doing important conceptual writing work are some of the most valuable participants in the arena. After all, nearly all of human epistemic and technological development has been conveyed through the medium of text. What are mathematicians if not amazing technical communicators?
I guess you need to hire engineers who also enjoy writing and are good at it.
This would seem to be a sign that some changes are needed to make it into a career people actually want to do. Perhaps it's at simple as paying more, though probably other changes in workflow/working conditions/status (all correlated with pay) are what would really help the most.
No one gets promoted for good documentation. It just has to be good enough for the promo panel to skim through and be impressed, lots of nice large percent results too. But not good enough for a system to be maintained, or an on-call to work on, or someone new to contribute to.
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.