15 ms·

How to avoid being a secretary for engineers (2018)

106 points by SenHeng 4y ago

Mertax 4y ago
At our organization we have a nontechnical sprint tester that executes manual tests and creates customer facing documentation. This sprint tester is part of our pull request approvals on our new feature branch builds. The engineers write the unit tests, integration tests and create the initial draft of a manually executed (zephyr) test. The sprint tester enhances the manual test and also creates the customer facing documentation/training content. What’s been nice about this is if the sprint tester finds its overly complicated to explain a new feature they can provide feedback about the design before it gets merged into the production builds. In this way they’re not just documenting what’s been done, but are contributing to the design.
bhawks 4y ago
Teams that really deliver well pull folks that work in supporting roles into the engineering & product team culture. Transactional relationships hit limits depressingly quickly - they also become toxic in ways that hurt the product you're trying to build. If you treat your supports as equal team members you can attract and retain amazing talent that helps you iterate and deliver good products quickly. If you throw tasks over the wall and let people indulge in power fantasies you're wasting your time.
- austinshea 4y ago
  very well said
  - fuzzfactor 4y ago
    >pull folks that work in supporting roles into the engineering & product team culture. This can be one of the good ways to get something like a team of 10 (consisting of 5 engineers and 5 non-engineers), to outperform 10 engineers in a culture where they have much less integration with the non-engineering employees. Some projects are based on a (big?) complex idea of a single outstanding specialized engineer. If the project or prototype is to be advanced or completed single-handedly, it's essential for that engineer to have enough knowledge & ability, often without very many notes and data, so they could halt the project at any time, then fully produce as detailed documentation as necessary only after the engineering itself is over. At least for that particular milestone. That would be the only time it was finally no longer a moving target. From that point with hindsight, depending on the degree of thoroughness needed, that top engineer can then justify a period of non-progress while they sit down and focus on fully appropriate documentation for that exact completed or halted project. That would be an engineer who was expected to be an accomplished technical writer already beforehand. With the knowledge of what this kind of final thorough documentation would look like the whole time, since even before the project got underway, the interim note-taking and essential micro-subdocumentation tasks could be anywhere from truly minimal to almost-publishable as you go along. Depends on how the engineering process is slowed by having the engineer spend more time sitting down producing interim documentation, when real progress might be completely dependent on them not sitting down. Whether or not they are actually running around designing, building, or testing "engines" the entire time they are not remaining seated. Not every kind of engine is needed for a rocket, but every kind of rocket needs an engine. But you don't get to the moon single-handedly. The reason a team is then often formed can be because one engineer is simply not enough for the size of the project, or it can greatly expedite the completion of subengineering components. The reason to have a dedicated writer is the same reason to have a team to begin with. For a multi-year project, if you're going to document it thoroughly, the top writer will be working closely with the top engineer for quite a while. Take advantage of that time so a lot of learning takes place in both directions. Nothing else comes close. Now there are times when the top writer needs to be the second engineer, so the top engineer can focus only on the engines themselves, and it needs to be accepted that a very capable second engineer will be focused intensively on documentation rather than engines of their own for that period. Ideally final editorial review can be made by an accomplshed technical journalist without the need for the editor to be very familir with that exact engineering discipline. This does require that the second engineer rise to a certain level of journalistic sophistication, probably best if an entire engineering culture can do it. Very few things are ideal. In another part of the spectrum, every engineer may have more than one engine and there's no way that's going to be thoroughly documented no matter what. Even if each engineer had their own professional journalist, if the engineers are being streched thin so is the documentation. This is where the technical writer can feel like a bewildered scribe. And everything in between. So I really admire the author's actions to step up to the plate to handle the more difficult situations by improving their actual engineering familiarities & abilities as journalists. If the top writer is going to be a professional journalist instead of the second engineer, the writer still needs to spend a great deal of time along with the second engineer in the room with the engine. And fundamental questions from the writer need to be answered to good journalistic satisfaction as documentation goes along. If the witer can not be recognized as one of the essential engineering team members in this case, you're not getting your money's worth. Like it says in the article, it's more than just documentation, it's communication. And with so many projects the only thing you have to show for it afterward is the paperwork. So engineers need to step up to the plate to do their share to make better documentation possible to begin with.
brutusborn 4y ago
I've never understood writing as a specialization without any subject matter knowledge. For example Journalism degrees are often the first step in becoming a writer for a newspaper. The journalist ends up in the 'business' or 'politics' team even with no experience in these fields. My naive suggestion for improvement would be to develop technical writing skills in addition to another degree or field. Want to write about science? Then do a science degree as well as a writing course. Same with documenting software. Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics. I think the article supports my view. The author hit a limit at his workplace because he specialised in writing without a deeper knowledge of what he was writing about. Instead of gaining that knowlege prior to working he had to learn on the job, which is fine but not ideal if it's not necessary.
- WalterBright 4y ago
  Journalists writing well but ignorantly about a topic is the result, and commonplace.
  - trashtester 4y ago
    Not only is this depressing, but it can lead to dangerous misinformation.
    - WalterBright 4y ago
      Every time I've seen a journalist report on a topic that I have in-depth knowledge of, the article was misleading and usually flat out wrong. This is even when the journalist has no bias. When the journalist does have a bias, it's just worse. Over time this has made me suspicious of all reporting by journalists. The reporting on the 737MAX is a stellar example of this. The only reasonably accurate reporting I've seen on it is by Aviation Week.
- teeray 4y ago
  > Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics. I would say that’s probably about as much as you would want. The best technical writer I ever worked with went from basic computer skills to becoming an expert at deploying and configuring the database software we developed on myriad infrastructure. The newcomer’s mindset helped make the writing wonderfully approachable for anyone to read. The process was always something like: 1) Learn how to do the thing, but ask really good questions along the way (I often reconsidered some of my own design choices from those questions) 2) Use the gathered information to write about doing the thing.
warcher 4y ago
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
awill88 4y ago
I was joking with my boss the other day that the way I start out my technical writing (which I hate because it is such a different skill set) is to start “talking shit” and then I self-edit based on the fear that someone is going to call me out for this or that, and then I have my boss look at it and edit it before it goes anywhere. It’s my new framing of it because I think that storytelling is fundamental to producing useful information. Also, I was a drama major w/ comp sci minor, so I’m probably doing what I was meant to. Technical writing should evoke emotions, not at 6 or above in a 1-10 scale of intensity, but shit, say something or what’s the point? There’s always drama at work with enough people, always politics. Sprinkling a bit of that is actually healthy imho. Not that you want cringe, but the tone, it’s colored different, when you are describing why port numbers were chosen, for example. Tell people stories. Also, be willing to invite someone else to shape and change even the things you feel the most conviction about. Too often we put ourselves into a cultural prison where we insist on making measurable contributions like an API or some cool feature that we can “specialize” in. Specialize on your own time, that’s my advice. At work, do something special, don’t specialize. It’s a myth.
O__________O 4y ago
____Response to Article____ Engineers are rarely good at writing technical documentation, especially compared to technical writers (that is “secretaries” per author’s lingo) which by definition, should be. Engineers generally cost more than technical writers. Good technical writing saves engineering time both during AND after the documentation is produced. Author spends large amount of time, to poorly express that to be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context. ____System for to Producing Tech Docs____ Anyone looking for a good system of producing documentation should check out: https://documentation.divio.com/ https://documentation.divio.com/ Which has a 30-min presentation: https://m.youtube.com/watch?v=t4vKPhjcMZg https://m.youtube.com/watch?v=t4vKPhjcMZg Prior HN posts on the system are here: https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio.com%2F https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....

106 points by SenHeng 4y ago

At our organization we have a nontechnical sprint tester that executes manual tests and creates customer facing documentation. This sprint tester is part of our pull request approvals on our new feature branch builds. The engineers write the unit tests, integration tests and create the initial draft of a manually executed (zephyr) test. The sprint tester enhances the manual test and also creates the customer facing documentation/training content. What’s been nice about this is if the sprint tester finds its overly complicated to explain a new feature they can provide feedback about the design before it gets merged into the production builds. In this way they’re not just documenting what’s been done, but are contributing to the design.

bhawks 4y ago

Teams that really deliver well pull folks that work in supporting roles into the engineering & product team culture. Transactional relationships hit limits depressingly quickly - they also become toxic in ways that hurt the product you're trying to build. If you treat your supports as equal team members you can attract and retain amazing talent that helps you iterate and deliver good products quickly. If you throw tasks over the wall and let people indulge in power fantasies you're wasting your time.

austinshea 4y ago
very well said
- fuzzfactor 4y ago
  >pull folks that work in supporting roles into the engineering & product team culture. This can be one of the good ways to get something like a team of 10 (consisting of 5 engineers and 5 non-engineers), to outperform 10 engineers in a culture where they have much less integration with the non-engineering employees. Some projects are based on a (big?) complex idea of a single outstanding specialized engineer. If the project or prototype is to be advanced or completed single-handedly, it's essential for that engineer to have enough knowledge & ability, often without very many notes and data, so they could halt the project at any time, then fully produce as detailed documentation as necessary only after the engineering itself is over. At least for that particular milestone. That would be the only time it was finally no longer a moving target. From that point with hindsight, depending on the degree of thoroughness needed, that top engineer can then justify a period of non-progress while they sit down and focus on fully appropriate documentation for that exact completed or halted project. That would be an engineer who was expected to be an accomplished technical writer already beforehand. With the knowledge of what this kind of final thorough documentation would look like the whole time, since even before the project got underway, the interim note-taking and essential micro-subdocumentation tasks could be anywhere from truly minimal to almost-publishable as you go along. Depends on how the engineering process is slowed by having the engineer spend more time sitting down producing interim documentation, when real progress might be completely dependent on them not sitting down. Whether or not they are actually running around designing, building, or testing "engines" the entire time they are not remaining seated. Not every kind of engine is needed for a rocket, but every kind of rocket needs an engine. But you don't get to the moon single-handedly. The reason a team is then often formed can be because one engineer is simply not enough for the size of the project, or it can greatly expedite the completion of subengineering components. The reason to have a dedicated writer is the same reason to have a team to begin with. For a multi-year project, if you're going to document it thoroughly, the top writer will be working closely with the top engineer for quite a while. Take advantage of that time so a lot of learning takes place in both directions. Nothing else comes close. Now there are times when the top writer needs to be the second engineer, so the top engineer can focus only on the engines themselves, and it needs to be accepted that a very capable second engineer will be focused intensively on documentation rather than engines of their own for that period. Ideally final editorial review can be made by an accomplshed technical journalist without the need for the editor to be very familir with that exact engineering discipline. This does require that the second engineer rise to a certain level of journalistic sophistication, probably best if an entire engineering culture can do it. Very few things are ideal. In another part of the spectrum, every engineer may have more than one engine and there's no way that's going to be thoroughly documented no matter what. Even if each engineer had their own professional journalist, if the engineers are being streched thin so is the documentation. This is where the technical writer can feel like a bewildered scribe. And everything in between. So I really admire the author's actions to step up to the plate to handle the more difficult situations by improving their actual engineering familiarities & abilities as journalists. If the top writer is going to be a professional journalist instead of the second engineer, the writer still needs to spend a great deal of time along with the second engineer in the room with the engine. And fundamental questions from the writer need to be answered to good journalistic satisfaction as documentation goes along. If the witer can not be recognized as one of the essential engineering team members in this case, you're not getting your money's worth. Like it says in the article, it's more than just documentation, it's communication. And with so many projects the only thing you have to show for it afterward is the paperwork. So engineers need to step up to the plate to do their share to make better documentation possible to begin with.

brutusborn 4y ago

I've never understood writing as a specialization without any subject matter knowledge. For example Journalism degrees are often the first step in becoming a writer for a newspaper. The journalist ends up in the 'business' or 'politics' team even with no experience in these fields. My naive suggestion for improvement would be to develop technical writing skills in addition to another degree or field. Want to write about science? Then do a science degree as well as a writing course. Same with documenting software. Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics. I think the article supports my view. The author hit a limit at his workplace because he specialised in writing without a deeper knowledge of what he was writing about. Instead of gaining that knowlege prior to working he had to learn on the job, which is fine but not ideal if it's not necessary.

WalterBright 4y ago
Journalists writing well but ignorantly about a topic is the result, and commonplace.
- trashtester 4y ago
  Not only is this depressing, but it can lead to dangerous misinformation.
  - WalterBright 4y ago
    Every time I've seen a journalist report on a topic that I have in-depth knowledge of, the article was misleading and usually flat out wrong. This is even when the journalist has no bias. When the journalist does have a bias, it's just worse. Over time this has made me suspicious of all reporting by journalists. The reporting on the 737MAX is a stellar example of this. The only reasonably accurate reporting I've seen on it is by Aviation Week.
teeray 4y ago
> Isn't it better to have knowledge about software when writing documentation? I'm not talking advanced CS here, I mean basics. I would say that’s probably about as much as you would want. The best technical writer I ever worked with went from basic computer skills to becoming an expert at deploying and configuring the database software we developed on myriad infrastructure. The newcomer’s mindset helped make the writing wonderfully approachable for anyone to read. The process was always something like: 1) Learn how to do the thing, but ask really good questions along the way (I often reconsidered some of my own design choices from those questions) 2) Use the gathered information to write about doing the thing.

warcher 4y ago

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

awill88 4y ago

I was joking with my boss the other day that the way I start out my technical writing (which I hate because it is such a different skill set) is to start “talking shit” and then I self-edit based on the fear that someone is going to call me out for this or that, and then I have my boss look at it and edit it before it goes anywhere. It’s my new framing of it because I think that storytelling is fundamental to producing useful information. Also, I was a drama major w/ comp sci minor, so I’m probably doing what I was meant to. Technical writing should evoke emotions, not at 6 or above in a 1-10 scale of intensity, but shit, say something or what’s the point? There’s always drama at work with enough people, always politics. Sprinkling a bit of that is actually healthy imho. Not that you want cringe, but the tone, it’s colored different, when you are describing why port numbers were chosen, for example. Tell people stories. Also, be willing to invite someone else to shape and change even the things you feel the most conviction about. Too often we put ourselves into a cultural prison where we insist on making measurable contributions like an API or some cool feature that we can “specialize” in. Specialize on your own time, that’s my advice. At work, do something special, don’t specialize. It’s a myth.

O__________O 4y ago

____Response to Article____ Engineers are rarely good at writing technical documentation, especially compared to technical writers (that is “secretaries” per author’s lingo) which by definition, should be. Engineers generally cost more than technical writers. Good technical writing saves engineering time both during AND after the documentation is produced. Author spends large amount of time, to poorly express that to be a good technical writer, you must understand who needs what and why, then figure out how to solve that the best way based on the context. ____System for to Producing Tech Docs____ Anyone looking for a good system of producing documentation should check out: https://documentation.divio.com/ https://documentation.divio.com/ Which has a 30-min presentation: https://m.youtube.com/watch?v=t4vKPhjcMZg https://m.youtube.com/watch?v=t4vKPhjcMZg Prior HN posts on the system are here: https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio.com%2F https://hn.algolia.com/?q=https%3A%2F%2Fdocumentation.divio....