4 ms·

As much as I appreciate a well turned phrase, I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the top

As much as I appreciate a well turned phrase, I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the topic. I find tech writing skill to be necessary but not sufficient to competent at technical writing. GPT-3 is more than sufficient if my goal is phrases that sound reasonable may or may not capture the essential concepts

DoingIsLearning 4y ago
> I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the topic. It really depends on who the target audience is. If we are writing for other engineers on the inner workings then yes maybe an engineer from within the team will probably be better suited. However, if it is a technical file for an external audience or regulatory work I would much rather have an experienced 'Analyst' or 'Systems Eng' (in the requirements sense of the title not sys eng in the US infrastructure sense of the word) do the write up. We as technical people vastly underestimate how crap we are at explaining things to someone without the very problem-specific domain knowledge.
trashtester 4y ago
The primary author of the text must understand what is to be communicated AT LEAST as well as the target audience. If you are supposed to write a user manual for the next iPhone, the main trick is not technical, but rather to figure out of to structure relatively simple information in a way that even your mother can understand. Still, it's probably a good idea to have an engineer go over the text after, to make sure there are no glaring errors. If on, the other hand, you write documentation for Apache Spark, you probably need to be a pretty competent computer scientist, data engineer or data scientist. Maybe a tech writer can go over the text after, but they will probably not be able to understand the content, so can do little beyond formatting, language and structure (and even that needs to be reviewed by a real tech person after). In the latter case, it may be VERY useful for the tech person to have some formal training in technical writing, in addition to be the kind of engineer that is also pretty good with language and presentation.
TheJoeMan 4y ago
It would be interesting if the Author instead turned in a less-effort, sloppier documentation that just stuck to the haphazard bullet points, to provide contrast to their optimized work. The issue with making complex things simple is just that - it looks so simple.

DoingIsLearning 4y ago

> I am highly suspicious about reading documentation written by someone who doesn’t fundamentally understand the topic. It really depends on who the target audience is. If we are writing for other engineers on the inner workings then yes maybe an engineer from within the team will probably be better suited. However, if it is a technical file for an external audience or regulatory work I would much rather have an experienced 'Analyst' or 'Systems Eng' (in the requirements sense of the title not sys eng in the US infrastructure sense of the word) do the write up. We as technical people vastly underestimate how crap we are at explaining things to someone without the very problem-specific domain knowledge.

trashtester 4y ago

The primary author of the text must understand what is to be communicated AT LEAST as well as the target audience. If you are supposed to write a user manual for the next iPhone, the main trick is not technical, but rather to figure out of to structure relatively simple information in a way that even your mother can understand. Still, it's probably a good idea to have an engineer go over the text after, to make sure there are no glaring errors. If on, the other hand, you write documentation for Apache Spark, you probably need to be a pretty competent computer scientist, data engineer or data scientist. Maybe a tech writer can go over the text after, but they will probably not be able to understand the content, so can do little beyond formatting, language and structure (and even that needs to be reviewed by a real tech person after). In the latter case, it may be VERY useful for the tech person to have some formal training in technical writing, in addition to be the kind of engineer that is also pretty good with language and presentation.

TheJoeMan 4y ago

It would be interesting if the Author instead turned in a less-effort, sloppier documentation that just stuck to the haphazard bullet points, to provide contrast to their optimized work. The issue with making complex things simple is just that - it looks so simple.