Notes on Technical Writing(mkaz.blog)
mkaz.blog
Notes on Technical Writing
https://mkaz.blog/misc/notes-on-technical-writing/
15 comments
A fair observation. I do think there's some value to concerns over style, but far too many tech writers give them undue prominence.
I couldn't champion your bulleted points harder. Honestly, if I had a say in it, any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library.
Just as tech writers in the medical field need to know quite a bit about medicine, tech writers in software should be required to know quite a bit about engineering software. There's plenty that do, but there's also quite a few that don't--I think it's a side effect of the field's relative youth.
I really wish more writers would code and do exactly the things you mention, such as implement robust code sample testing, etc.
The ideal technical writer, at least for software engineering documentation, is a hybrid of a traditional technical writer and a software engineer[^1].
[^1]: This excludes user-facing software documentation, which is essentially a totally different field than those that deal with writing for developer or engineer audiences.
I couldn't champion your bulleted points harder. Honestly, if I had a say in it, any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library.
Just as tech writers in the medical field need to know quite a bit about medicine, tech writers in software should be required to know quite a bit about engineering software. There's plenty that do, but there's also quite a few that don't--I think it's a side effect of the field's relative youth.
I really wish more writers would code and do exactly the things you mention, such as implement robust code sample testing, etc.
The ideal technical writer, at least for software engineering documentation, is a hybrid of a traditional technical writer and a software engineer[^1].
[^1]: This excludes user-facing software documentation, which is essentially a totally different field than those that deal with writing for developer or engineer audiences.
The problem with your perspective is an economic one. If you have the chops to be a hybrid TW/SWE, you will never take a tech writing job (or get out of tech writing as soon as you can) because tech writers simply make substantially less than engineers. Everyone acknowledges that tech writing is vital but until the pay story reflects that the status quo will persist.
> ...any tech writer working on developer documentation should be able to code/build/perform/use whatever task or api they're documenting without the help of an engineer. They should be able to read and understand code, and they should be willing to do so, even more so than the average engineer using some library code. They should be capable of understanding a library deeply and synthesizing and summarizing that understanding for users of the library.
This is what made my friend Caroline Rose such a great technical writer. She not only can explain things in clear and simple terms, but she was also an accomplished programmer before branching into technical writing.
Here is a story about the documentation that became Inside Macintosh:
> I sat down to meet with Caroline for the first time, and she couldn't have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn't mind admitting it when she didn't understand something, and she wouldn't stop badgering me until she comprehended every nuance. She began to ask me questions that I didn't know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there.
> Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her.
https://www.folklore.org/StoryView.py?story=Inside_Macintosh...
One of my favorite examples from _Inside Macintosh_ is the discussion about the mathematical foundation of QuickDraw. Modern graphic programmers all know that a (0,0,0,0) rectangle is an empty rectangle. But why is that? Why isn't it a single pixel?
The explanation on pages I-138 through I-141 is what made this concept make sense to me. Here's a PDF of _Inside Macintosh_:
http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_...
Besides that section, there are all kinds of examples of how to explain a complicated concept in simple and understandable terms. It's worth a quick skim of the entire book to see what good documentation looks like.
This is what made my friend Caroline Rose such a great technical writer. She not only can explain things in clear and simple terms, but she was also an accomplished programmer before branching into technical writing.
Here is a story about the documentation that became Inside Macintosh:
> I sat down to meet with Caroline for the first time, and she couldn't have been more different than the previous writer. As soon as I began to explain the first routine, she started bombarding me with questions. She didn't mind admitting it when she didn't understand something, and she wouldn't stop badgering me until she comprehended every nuance. She began to ask me questions that I didn't know the answers to, like what happened when certain parameters were invalid. I had to keep the source code open on the screen of my Lisa when I met with her, so I could figure out the answers to her questions while she was there.
> Pretty soon, I figured out that if Caroline had trouble understanding something, it probably meant that the design was flawed. On a number of occasions, I told her to come back tomorrow after she asked a penetrating question, and revised the API to fix the flaw that she had pointed out. I began to imagine her questions when I was coding something new, which made me work harder to get things clearer before I went over them with her.
https://www.folklore.org/StoryView.py?story=Inside_Macintosh...
One of my favorite examples from _Inside Macintosh_ is the discussion about the mathematical foundation of QuickDraw. Modern graphic programmers all know that a (0,0,0,0) rectangle is an empty rectangle. But why is that? Why isn't it a single pixel?
The explanation on pages I-138 through I-141 is what made this concept make sense to me. Here's a PDF of _Inside Macintosh_:
http://www.weihenstephan.org/~michaste/pagetable/mac/Inside_...
Besides that section, there are all kinds of examples of how to explain a complicated concept in simple and understandable terms. It's worth a quick skim of the entire book to see what good documentation looks like.
The issue with that though is that if someone could read/write code, they would probably choose to be a SWE instead of a tech writer.
I'm not sure why this is, but I suspect that it's an combination of higher pay and an interest in writing code over writing documentation.
In my experience I would say that a good SWE will attempt to write good documentation, as having to answer questions in the future about how stuff works over and over takes more time than just documenting things properly the first time.
I'm not sure why this is, but I suspect that it's an combination of higher pay and an interest in writing code over writing documentation.
In my experience I would say that a good SWE will attempt to write good documentation, as having to answer questions in the future about how stuff works over and over takes more time than just documenting things properly the first time.
How does one become a technical writer? I'm a software engineer, and e.g. I recently applied to Google for both a tech writer position and a software engineer position, and they interviewed me and offered me a job for the software engineer role but they gave me a form rejection for the tech writer role. I worry I'm stuck as a software engineer because that's what's on my resume.
Writing something substantial and posting it online would help your chances. I was offered a job as a technical writer partly on that basis. I agree with the other comment that software development is preferable for the money, but on the other hand it's easier to switch off from technical writing at the end of the day or do your own projects after work than it would be if you were programming all day.
While I'm at it, being a technical writer convinced me that software engineering and technical writing shouldn't be separate roles, because a lot of my time spent asking for clarification about things led to software engineers realizing they shouldn't have done it that way in the first place, and then changing it. If they had to write about it themselves, the feedback loop would have been tighter. Making them separate roles and paying technical writers less money probably started as some business guy's idea of division of labor.
While I'm at it, being a technical writer convinced me that software engineering and technical writing shouldn't be separate roles, because a lot of my time spent asking for clarification about things led to software engineers realizing they shouldn't have done it that way in the first place, and then changing it. If they had to write about it themselves, the feedback loop would have been tighter. Making them separate roles and paying technical writers less money probably started as some business guy's idea of division of labor.
Also, document the data model more than how the code works. Famous Linus Torvalds quote: "Bad programmers worry about the code. Good programmers worry about data structures and their relationships."
I don't see where he says anything about style. Could you point out to me what he says that makes you think that?
He does say to use bullet lists, but I think this is more about structuring the content and breaking ideas into steps than it is about style or formatting.
His points all seem to focus on providing clarity and useful content to the reader and user.
He does say to use bullet lists, but I think this is more about structuring the content and breaking ideas into steps than it is about style or formatting.
His points all seem to focus on providing clarity and useful content to the reader and user.
> Could you point out to me what he says that makes you think that?
I'd consider all of the following to be mostly style choices:
* Avoid Meta Writing
* Minimalist Instruction
* The "Constructivism" section, e.g.--Engage in an active dialog, invite users to act “Please try”, “See what happens”, “Explore yourself”
(The above is now what I'd estimate to be like 80% of the article)
The reason why I'd consider that a style is that if you buy a style guide, e.g. the IBM style guide, it would include similar instructions, e.g. "avoid passive voice" or "be more succinct" (though at a more of an implementation level).
It's possible you'd have a better name for it than 'style'. I'd accept that. My original point stands though; most TWs I've seen concern themselves with the letters of the documentation, and omit what I'd consider the most useful about documentation, that is the deep technical details such as maintaining code samples, or writing test suite for the documentation.
I'd consider all of the following to be mostly style choices:
* Avoid Meta Writing
* Minimalist Instruction
* The "Constructivism" section, e.g.--Engage in an active dialog, invite users to act “Please try”, “See what happens”, “Explore yourself”
(The above is now what I'd estimate to be like 80% of the article)
The reason why I'd consider that a style is that if you buy a style guide, e.g. the IBM style guide, it would include similar instructions, e.g. "avoid passive voice" or "be more succinct" (though at a more of an implementation level).
It's possible you'd have a better name for it than 'style'. I'd accept that. My original point stands though; most TWs I've seen concern themselves with the letters of the documentation, and omit what I'd consider the most useful about documentation, that is the deep technical details such as maintaining code samples, or writing test suite for the documentation.
First, let me get on the same page about your parent comment:
> A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.
In general I agree that there are some technical writers who focus way too much on style. I also think that the list of practices that you described --- usability editing your docs, using a CI system and importing sections of the code samples into the docs to ensure that they're always working, being politically forceful about making sure that docs are treated as part of the core product and not an afterthought --- are all great practices. I agree that the practices you described should be established first before any debates about style.
Moving on, I emphatically disagree that minimalist and constructivist instruction are "style" considerations.
Style considerations are arbitrary decisions that you consistently follow in order to convey a sense of professionalism. In your first comment you provided a perfect example of a style consideration: title capitalization (e.g. whether to format your title like this "How to debug your code" or like this "How To Debug Your Code"). If we A/B tested a document to see if there was any change in user success rate based on title capitalization, there would be no difference.
Minimalist and constructivist instruction are guidelines on how to create effective instruction. For example, the minimalist guideline to explain how to recover from errors is a hugely valuable practice which is extremely obvious once you are exposed to the idea, but is somehow a practice that many forget to do.
To put it another way, if we A/B test a documentation set that follows minimalist or constructivist guidelines with a documentation set written by someone who doesn't understand those principles, I will wager money that the minimalist/constructivist doc set will lead to higher user success rates, however we agree to objectively measure that.
Avoiding passive voice is another example of something that may seem like a style consideration but actually goes a long way towards making your communication much more effective. The problem with the passive voice is that it often makes the subject of an action ambiguous. For example if you write "the script is updated" it's not clear who updates the script. If it's something that the user needs to do, it's much better to say "you need to update the script". If the user reads the passive phrasing "the script is updated" and they don't understand that they need to take an action, that's the potential difference between user success and failure.
As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style". This is the equivalent of saying "most software engineers are code monkeys with no social skills" and it's really damaging to the credibility of my industry. But I do agree that there are some who focus too much on that BS and you have my word that I'm trying to rid my industry of that bad habit.
> A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.
In general I agree that there are some technical writers who focus way too much on style. I also think that the list of practices that you described --- usability editing your docs, using a CI system and importing sections of the code samples into the docs to ensure that they're always working, being politically forceful about making sure that docs are treated as part of the core product and not an afterthought --- are all great practices. I agree that the practices you described should be established first before any debates about style.
Moving on, I emphatically disagree that minimalist and constructivist instruction are "style" considerations.
Style considerations are arbitrary decisions that you consistently follow in order to convey a sense of professionalism. In your first comment you provided a perfect example of a style consideration: title capitalization (e.g. whether to format your title like this "How to debug your code" or like this "How To Debug Your Code"). If we A/B tested a document to see if there was any change in user success rate based on title capitalization, there would be no difference.
Minimalist and constructivist instruction are guidelines on how to create effective instruction. For example, the minimalist guideline to explain how to recover from errors is a hugely valuable practice which is extremely obvious once you are exposed to the idea, but is somehow a practice that many forget to do.
To put it another way, if we A/B test a documentation set that follows minimalist or constructivist guidelines with a documentation set written by someone who doesn't understand those principles, I will wager money that the minimalist/constructivist doc set will lead to higher user success rates, however we agree to objectively measure that.
Avoiding passive voice is another example of something that may seem like a style consideration but actually goes a long way towards making your communication much more effective. The problem with the passive voice is that it often makes the subject of an action ambiguous. For example if you write "the script is updated" it's not clear who updates the script. If it's something that the user needs to do, it's much better to say "you need to update the script". If the user reads the passive phrasing "the script is updated" and they don't understand that they need to take an action, that's the potential difference between user success and failure.
As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style". This is the equivalent of saying "most software engineers are code monkeys with no social skills" and it's really damaging to the credibility of my industry. But I do agree that there are some who focus too much on that BS and you have my word that I'm trying to rid my industry of that bad habit.
> To put it another way, if we A/B test a documentation set that follows minimalist or constructivist guidelines with a documentation set written by someone who doesn't understand those principles, I will wager money that the minimalist/constructivist doc set will lead to higher user success rates, however we agree to objectively measure that.
Sure. What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later. Consequently, focus on minimalism should come after focus on technical expertise, which is not my experience (and I would go as far to say that it's not the practise of something like 80% of the field).
> As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style".
I did say that. I said:
- "... most TWs I've seen ..."
- "A lot of technical writers focus ..."
- "... I've seen tech writers have ..."
I'll grant that there's missing one "... I've seen" in the list above :). But, of course it's only my experience. I don't know tech writers at Google, for example, or Amazon.
> This is the equivalent of saying "most software engineers are code monkeys with no social skills"
It's not because of the ad-hominem.
Sure. What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later. Consequently, focus on minimalism should come after focus on technical expertise, which is not my experience (and I would go as far to say that it's not the practise of something like 80% of the field).
> As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style".
I did say that. I said:
- "... most TWs I've seen ..."
- "A lot of technical writers focus ..."
- "... I've seen tech writers have ..."
I'll grant that there's missing one "... I've seen" in the list above :). But, of course it's only my experience. I don't know tech writers at Google, for example, or Amazon.
> This is the equivalent of saying "most software engineers are code monkeys with no social skills"
It's not because of the ad-hominem.
Yes we're in agreement that usability editing your docs and building automated processes that ensure that docs stay usable over time are the #1 priority.
> What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later.
Yes, also in agreement here. Usable docs is the table stakes.
Sorry about putting words in your mouth! I must have got triggered and jumped the gun without being very careful about looking at the exact words you used.
> What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later.
Yes, also in agreement here. Usable docs is the table stakes.
Sorry about putting words in your mouth! I must have got triggered and jumped the gun without being very careful about looking at the exact words you used.
With the caveat that I may be projecting or reasoning from a biased sample, I had two thoughts:
1. I think the faults you're picking on in documentation are valid, important, and also probably more organizational/management faults than TWs.
If the people who have to pay employees tend to be willing to pay developers more than they're willing to pay writers, it seems like the best "average" outcome you can expect--even if you go looking for tech writers who know how to develop--is that you get tech writers who can't or don't want to earn more money developing (i.e., they prefer writing over developing strongly enough to turn down the extra pay, don't have the skill/experience to earn more developing, and so on).
Dev/ops tools, methods, and thinking have a lot to bring to tech writing--but I can't imagine many orgs/projects can achieve this without a collaboration between developers and tech writers, or developer-writers sufficiently remunerated for possessing both skillsets.
2. Style issues in writing are much like those in programming. Code style doesn't matter a whole lot when it's a one-developer code base, but it definitely starts to matter when there are more chefs in the kitchen. When you don't nail down what the style is in either domain, everyone follows personal preference. It can work for a while, but it tends towards chaos that requires a lot more work to clean up than it would to be consistent in the first place.
Edit: This isn't to say you aren't right, but that the style issues are a sort of maintenance issue that may seem pointless from the outside but also do need to get settled (though, ideally without extended bikeshedding...)
1. I think the faults you're picking on in documentation are valid, important, and also probably more organizational/management faults than TWs.
If the people who have to pay employees tend to be willing to pay developers more than they're willing to pay writers, it seems like the best "average" outcome you can expect--even if you go looking for tech writers who know how to develop--is that you get tech writers who can't or don't want to earn more money developing (i.e., they prefer writing over developing strongly enough to turn down the extra pay, don't have the skill/experience to earn more developing, and so on).
Dev/ops tools, methods, and thinking have a lot to bring to tech writing--but I can't imagine many orgs/projects can achieve this without a collaboration between developers and tech writers, or developer-writers sufficiently remunerated for possessing both skillsets.
2. Style issues in writing are much like those in programming. Code style doesn't matter a whole lot when it's a one-developer code base, but it definitely starts to matter when there are more chefs in the kitchen. When you don't nail down what the style is in either domain, everyone follows personal preference. It can work for a while, but it tends towards chaos that requires a lot more work to clean up than it would to be consistent in the first place.
Edit: This isn't to say you aren't right, but that the style issues are a sort of maintenance issue that may seem pointless from the outside but also do need to get settled (though, ideally without extended bikeshedding...)
Even a computer without installed dependencies should be able to follow the docs. Some don’t list what dependencies they need at the beginning, which could save a lot of time and error messages.
Totally agree with your points about code correctness. That's the most important thing. I spent probably a year making systems/tools/processes to ensure that every code snippet in our documentation is imported unmodified from a GitHub repo with CI attached and that people reading the docs can see that. It's been a huge win.
When I first saw the title I thought to myself, “shit, another random, possibly misleading post about technical writing?” but on quick review this seems to be a well-researched overview of the field. If you were to ask a practicing technical writer to present a summary like this, it wouldn’t differ much.
If the author is here, I’m curious if they took that definition of technical writing from my post? [1] To the best of my memory I feel like I came up with that definition on my own but also wouldn’t be surprised if I subconsciously took it from somewhere else.
[1] https://kayce.basqu.es/blog/metrics/
If the author is here, I’m curious if they took that definition of technical writing from my post? [1] To the best of my memory I feel like I came up with that definition on my own but also wouldn’t be surprised if I subconsciously took it from somewhere else.
[1] https://kayce.basqu.es/blog/metrics/
I am here, and I have read several of your posts, thanks for wonderful resource. So yes, it is quite possible I took the definition from you, I collected the various notes over time, so I'm not always positive where they come from.
Agreed! This was quite refreshing. There's some great advice in this piece.
An aside: did you redesign your website, Kayce? I recall it looking quite different in the past. It looks great! I like the aesthetic.
An aside: did you redesign your website, Kayce? I recall it looking quite different in the past. It looks great! I like the aesthetic.
Per Google & DDG y'all are the only two, exactly the same, wordings so I'd say they snipped it from you previously, Kayce :)
> In this time, I’ve read various resources on technical writing and documentation. These are my notes, both to help me remember later, but also as a tool to help me think about writing now.
and later, in an apparent contradiction ...
> You don’t need to tell the reader what you’re going to tell them. Just tell them.
I think this point could be fleshed out better.
Any piece of nonfiction writing, technical or otherwise, that doesn't give me a clear idea about its content may not pass my filter. I see this the most in long-form journalism. But it also pops up when authors focus on themselves, their struggles, and their aspirations in the first couple of paragraphs.
Telling the reader what they're about to read in the first paragraph of a technical piece is a courtesy. People are busy, and they don't have time to wade through a bunch of throat-clearing at the start of a piece. They'll just close the tab and move on.
and later, in an apparent contradiction ...
> You don’t need to tell the reader what you’re going to tell them. Just tell them.
I think this point could be fleshed out better.
Any piece of nonfiction writing, technical or otherwise, that doesn't give me a clear idea about its content may not pass my filter. I see this the most in long-form journalism. But it also pops up when authors focus on themselves, their struggles, and their aspirations in the first couple of paragraphs.
Telling the reader what they're about to read in the first paragraph of a technical piece is a courtesy. People are busy, and they don't have time to wade through a bunch of throat-clearing at the start of a piece. They'll just close the tab and move on.
This is a good counterpoint. After all, academic journals have abstracts for a reason--when people need to get something done, a synopsis quickly helps them make a decision as to whether or not they actually found the appropriate resource.
It goes both ways. I think this aspect of the craft is a bit more of an art than a science. At certain points it's appropriate to signal what you're about to discuss, at others, it's just noise.
In general, anything that functions similarly to an academic abstract is probably useful (saves the reader from potentially wasting time, gives an overview of the general subject matter and idea without delving into details, takes about 1 minute maximum to read).
It goes both ways. I think this aspect of the craft is a bit more of an art than a science. At certain points it's appropriate to signal what you're about to discuss, at others, it's just noise.
In general, anything that functions similarly to an academic abstract is probably useful (saves the reader from potentially wasting time, gives an overview of the general subject matter and idea without delving into details, takes about 1 minute maximum to read).
Abstract or "executive summary" is the paragraph right under the title that does this in everything I wrote for the exact purpose to give someone the opportunity to see whether this is his/her go-to document for a purpose or note. I always like to add/read the ToC, that is also a quick read to see if this doc is what I am/people are looking for.
I've also noticed that for some reason people get sloppy when writing posts about technical writing and forget to apply the principles of technical writing to that post. I avoid this bad habit by forcing myself to provide a summary for every post I create, e.g. https://kayce.basqu.es/blog/FAQs/
>I've also noticed that for some reason people get sloppy when writing posts about technical writing and forget to apply the principles of technical writing to that post.
Well, technically meta-posts about technical writing are not technical writing.
Well, technically meta-posts about technical writing are not technical writing.
I define technical writing as written communication where your main goal is to transfer knowledge. By that definition this post is technical writing.
Any piece about writing will violate its own rules. I think this could be a law ;)
This is because writing is hard. It is just like coding, in the sense that I can revise it three times and still find ways to make it better the fourth time, or the tenth time.
So no writing is perfect, but I think I can often tell when a writer has read the right books (like On Writing Well). Every now and then an article will jump out to me as being 10 times more lucid and concise than the norm --- even though it's still imperfect.
Also I think the rules are not black and white. There is some judgment needed at every turn. Sometimes you will want to bend one rule to preserve another, and people with different tastes will either praise you or blame you for how you make the call.
This is because writing is hard. It is just like coding, in the sense that I can revise it three times and still find ways to make it better the fourth time, or the tenth time.
So no writing is perfect, but I think I can often tell when a writer has read the right books (like On Writing Well). Every now and then an article will jump out to me as being 10 times more lucid and concise than the norm --- even though it's still imperfect.
Also I think the rules are not black and white. There is some judgment needed at every turn. Sometimes you will want to bend one rule to preserve another, and people with different tastes will either praise you or blame you for how you make the call.
I like the rule of three. Tell the reader what you are going to tell and why. Tell them in detail. Then in the conclusion summarize the main takeaway from what you just told them.
I've never understood the pre-summarization technique. I've had lecturers constantly state what they intend to say so much that its a distraction. When I see this style of writing I glaze over as well.
You haven't been spending too much time with COOs, CAE, CCOs, and other Cxx's. They need the executive summary (pre-summarization).
Some of the C-folk like: -single line (title) -one liner (more than 5 words but less than 20 words) -short paragraph (2-4 lines) -perhaps a RAG or something visual that will show sentiment (if/where appropriate)
and they won't read past that.
So when (I) write documentation/report/what-have-you I need to make one document for all audiences, the Cxx with 1-minute to spend and the actual target/doer that will spend X-days following up the darn thing.
Some of the C-folk like: -single line (title) -one liner (more than 5 words but less than 20 words) -short paragraph (2-4 lines) -perhaps a RAG or something visual that will show sentiment (if/where appropriate)
and they won't read past that.
So when (I) write documentation/report/what-have-you I need to make one document for all audiences, the Cxx with 1-minute to spend and the actual target/doer that will spend X-days following up the darn thing.
You pre-summarize, because you tell someone something, you tell them why you are telling them. So they can judge whether it is worth reading on. And to tell someone why, you have to state in a sentence or two what you are going to tell them.
The good thing about technical documents is that you can just skip the parts you don't want to read. But it is there for the people who do want to.
The good thing about technical documents is that you can just skip the parts you don't want to read. But it is there for the people who do want to.
I don't think it's an apparent contradiction. The first quote is a meta description of the whole article. People would need to know what it's about to read it.
In actual technical documentation, on the other hand, people already know "this is the documentation of program X". And in the various chapters, you can just go ahead and give them a good title, and then go say what it is to say - without first announcing what you'll say.
In actual technical documentation, on the other hand, people already know "this is the documentation of program X". And in the various chapters, you can just go ahead and give them a good title, and then go say what it is to say - without first announcing what you'll say.
I always try to understand the readers before writing a word. Why they are reading. And what they expect to be able to do better as a result of reading, or what decision they might be making.
If an author can't answer these questions, they will likely write something that is perceived as irrelevant, wrong, or simply 'meh'. This is especially true when writing 'technical reports' as opposed to documentation.
If an author can't answer these questions, they will likely write something that is perceived as irrelevant, wrong, or simply 'meh'. This is especially true when writing 'technical reports' as opposed to documentation.
"Know thy audience" and "know thy audience's purpose" are the cardinal rules of technical writing, as mentioned in Marcus's post. Often times there are limits to how much I can know about my audience. In that case it's especially helpful to put an "Assumptions" or "Intended audience" section at the top of a doc.
+1 on that "thy audience", and the audience is not just the end-users. It is the 10 extra layers/people that will get to carry an opinion (and whose opinion matters) by glancing a document for 1min or less.
"Don’t tell the reader something is extremely complex; likewise don’t tell the reader something is simple. The reader will make up their own mind about a concept being easy or hard."
I think this is great advice, and applied to teaching. I can't tell you the number of times a professor has said "and then obviously it follows that" or "it's easy to see that". Nearly every time that was uttered in a lecture I wanted to hurl my textbook at the board.
Looking for alternatives? "Is it easy?" or "It might be obvious" work fine. Maybe use those moments as opportunities to check in with your audience. In the written context, maybe offer end/footnotes explaining why it might be obvious/easy.
I think this is great advice, and applied to teaching. I can't tell you the number of times a professor has said "and then obviously it follows that" or "it's easy to see that". Nearly every time that was uttered in a lecture I wanted to hurl my textbook at the board.
Looking for alternatives? "Is it easy?" or "It might be obvious" work fine. Maybe use those moments as opportunities to check in with your audience. In the written context, maybe offer end/footnotes explaining why it might be obvious/easy.
Related: don't say someting is interesting. For example, "It's interesting that . . . " I see this preface more often than "simple" or "complex." Also there is a type of person for whom your introduction will come across as a dare to find it uninteresting.
[deleted]
Whenever I see this advice, or similar, I'm reminded of one of the "rules" I encountered in the style guide for an old MUD.
Roughly: Don't write item/place/npc descriptions that tell the player ("you") anything they should think or feel.
Easier said than done, though.
Roughly: Don't write item/place/npc descriptions that tell the player ("you") anything they should think or feel.
Easier said than done, though.
Most documentation is so bad and so often out-of-date that I can answer my question faster by reading the source (or tests).
Everything is so extremely verbose. I don't want to read a 7 paragraph essay about how this or that feature was developed and evolved over time; I just need a one line hint and maybe an example. Believe it or not, your software is not special. We've seen something like it before and get the gist already. I like the style of man pages, where everything is on one page and organized by the flag, i.e. actual usage (puts a hard limit on meandering bullshittery).
Everything is so extremely verbose. I don't want to read a 7 paragraph essay about how this or that feature was developed and evolved over time; I just need a one line hint and maybe an example. Believe it or not, your software is not special. We've seen something like it before and get the gist already. I like the style of man pages, where everything is on one page and organized by the flag, i.e. actual usage (puts a hard limit on meandering bullshittery).
> I like the style of man pages
You are in the minority, mate. Man pages are walls of text that cover too much detail in too little space. A lot of them lack examples.
Most people will take a simple task-oriented tutorial over an all-encompassing man page. That’s something that Microsoft understood very well back in the ‘90s, providing copious amounts of examples and tutorial on top of basic reference material. It’s part of the reason they saw orders of magnitude more adoption for their stack.
You are in the minority, mate. Man pages are walls of text that cover too much detail in too little space. A lot of them lack examples.
Most people will take a simple task-oriented tutorial over an all-encompassing man page. That’s something that Microsoft understood very well back in the ‘90s, providing copious amounts of examples and tutorial on top of basic reference material. It’s part of the reason they saw orders of magnitude more adoption for their stack.
Walls of text are great, just use / and search for what you want. Between that and command history, I think this is the best way to navigate software.
> Most documentation is so bad and so often out-of-date that I can answer my question faster by reading the source
Especially within a company. Once place I worked, a few teams liked to over-document, though it wasn't enforced org-wide. The docs were usually not very helpful, outdated, and yes, I could just read the code faster. I wish they put more effort into better factored code and better names.
Especially within a company. Once place I worked, a few teams liked to over-document, though it wasn't enforced org-wide. The docs were usually not very helpful, outdated, and yes, I could just read the code faster. I wish they put more effort into better factored code and better names.
Keep documentation close to the source to increase the odds it gets updated. Prefer READMEs to Wikis, and use source comments to generate docs rather than word/google docs. Some doc tools even test examples for you!
It's not perfect, and good documentation is an art, but if you care about your software and your users you'll try to communicate clearly.
It's not perfect, and good documentation is an art, but if you care about your software and your users you'll try to communicate clearly.
This is well done!
> Support error recognition and recovery.
I totally agree with this. You have to teach critical concepts a couple different ways in case one gets skimmed over or misunderstood. We rely on visuals for this--the text should stand independent of the photo / diagram, and vice versa.
I wrote a handbook on technical writing summing up what we've learned over many years of writing iFixit repair guides. https://help.dozuki.com/Tech_Writing/chapter/0
> Support error recognition and recovery.
I totally agree with this. You have to teach critical concepts a couple different ways in case one gets skimmed over or misunderstood. We rely on visuals for this--the text should stand independent of the photo / diagram, and vice versa.
I wrote a handbook on technical writing summing up what we've learned over many years of writing iFixit repair guides. https://help.dozuki.com/Tech_Writing/chapter/0
Another hugely important reason to support error recovery: this is how many people find documentation. They see an error when using an application (or writing code) and they copy-paste the error into a search engine. If you provide that error text verbatim in your documentation, you will capture that search engine traffic.
Tech Writing is a waterfall job.
What's needed is something more like peer review, where the "tech writer's" job is to ask hard question from the user POV during development - for varying values of "user", which would include customer, API consumer, and so on.
This wouldn't be code review, because it's about features, interfaces, and expected behaviours, not the fine details of implementation. And it wouldn't be a PM job, because it would be peer feedback in the form of dialog, not management in the form of requirements and specs.
And it should be continuous, so the doc base evolves in parallel with the code base.
And it should not be an afterthought.
This job does not exist yet. And it should, because virtually all orgs have a problem where individual developers become repositories of The Important Knowledge. If they leave it becomes hard to characterise system behaviours and architectures well enough to understand how they work well enough to replace/improve/reverse engineer them.
So IMO there's a niche for people who are competent developers, competent listeners, and competent communicators, who can pull it all together, stay on top of changes, and leave a readable record of the current state of institutional knowledge about projects, practices, stacks, and interfaces.
What's needed is something more like peer review, where the "tech writer's" job is to ask hard question from the user POV during development - for varying values of "user", which would include customer, API consumer, and so on.
This wouldn't be code review, because it's about features, interfaces, and expected behaviours, not the fine details of implementation. And it wouldn't be a PM job, because it would be peer feedback in the form of dialog, not management in the form of requirements and specs.
And it should be continuous, so the doc base evolves in parallel with the code base.
And it should not be an afterthought.
This job does not exist yet. And it should, because virtually all orgs have a problem where individual developers become repositories of The Important Knowledge. If they leave it becomes hard to characterise system behaviours and architectures well enough to understand how they work well enough to replace/improve/reverse engineer them.
So IMO there's a niche for people who are competent developers, competent listeners, and competent communicators, who can pull it all together, stay on top of changes, and leave a readable record of the current state of institutional knowledge about projects, practices, stacks, and interfaces.
I worked on designing and implementing a data architecture at a FAANG. One of the things we found worked well was bringing documentation as close as possible to source - that way, making changes to one but not the other has a high rate of getting caught during code reviews and documentation stays in sync. The challenge with this approach was then accessibility for non technical customers who don’t care for nor have reason to look at source. Instead of building documentation pages, we leveraged a system that was a registry of datasets, individual columns, use cases, and sample queries... it was tricky to get right but we implemented a pipeline where documentation from code would get propagated to this system automagically.
In terms of general technical writing, style is less of a concern I have. The real challenge is writing efficiently to convey sufficient information to the audience, without staying too high level but also not providing too many details. I often suffer from writers blockz
In terms of general technical writing, style is less of a concern I have. The real challenge is writing efficiently to convey sufficient information to the audience, without staying too high level but also not providing too many details. I often suffer from writers blockz
Anyone know where I can get legit technical writing gigs? I used to get paid to write about Elasticsearch for a company's blog and that was pretty cool. Would be keen to do something like that again. I can write about anything in the sysadmin/devops space or in the penetration testing space.
Thanks
Apply to a large company. Google, Microsoft, Apple, Amazon, all of these and many more have tech writers as a full time position.
Of course, there are not gigs. I know nothing of gigs to be honest.
Of course, there are not gigs. I know nothing of gigs to be honest.
Thanks, but I don't know if I'd wanna do this full time.
Hey Tim,
Upwork. Create a profile as a technical writer, and put links to your docs.
I've picked up partime gigs for API documentation, product usage documentation / User Guide, with screenshots and gifs on that platform. If you are US based, even better cos lot of Companies want to hire US based freelancer for TAX reasons and what not.
Upwork search for client even has a filter that says "US only" and I've used that as a client also, to hire freelancers from within US.
Besides traditional technical writing, there are also gigs for Technical blog posts on various subjects. Avoid the one-off gigs that are low paying, and focus on startups or companies that have already paid for other gigs (you can see it in their profile).
Upwork. Create a profile as a technical writer, and put links to your docs.
I've picked up partime gigs for API documentation, product usage documentation / User Guide, with screenshots and gifs on that platform. If you are US based, even better cos lot of Companies want to hire US based freelancer for TAX reasons and what not.
Upwork search for client even has a filter that says "US only" and I've used that as a client also, to hire freelancers from within US.
Besides traditional technical writing, there are also gigs for Technical blog posts on various subjects. Avoid the one-off gigs that are low paying, and focus on startups or companies that have already paid for other gigs (you can see it in their profile).
Thanks this is a good idea will give it a shot.
I am not US based I'm based in South Africa.
Do you enjoy writing documentation?
I actually found this article a bit confusing to read. I suppose they are "notes" but I found myself having to reread stuff a few times and it wasn't organized in a particularly clear way.
Here are some notes I had:
This is a very weird sentence:
> In the 1980s, they developed a minimalist approach and created a wonderful Operator Training Manual for the IBM Displaywriter, imagine having to introduce someone to using a word processor for the first time.
There is also a misspelling in "the four principals of minimalist instruction".
In that same section it is confusing to bullet point the four principles but include a summary of the principle at the end of the bullet point. This makes it hard to skim. (It's also self-referential, which the previous section recommends against.)
Here are some notes I had:
This is a very weird sentence:
> In the 1980s, they developed a minimalist approach and created a wonderful Operator Training Manual for the IBM Displaywriter, imagine having to introduce someone to using a word processor for the first time.
There is also a misspelling in "the four principals of minimalist instruction".
In that same section it is confusing to bullet point the four principles but include a summary of the principle at the end of the bullet point. This makes it hard to skim. (It's also self-referential, which the previous section recommends against.)
You will do really well as a proof-reader.
I’m a software engineer, but I have a degree in English lit. I find I love technical writing. Maybe it’s because I’m often writing about systems I built, so I understand them well and the writing comes fluidly — it might be less fun to write about systems I don’t know as well. Still, I find technical writing one of the parts of my job I most look forward to: presenting to my colleagues a proposed implementation, for example, is both a social aspect of engineering and a way to make sure your design is comprehensible and hence simple (simplicity being a hallmark of good design). I tend not to stress too much over whether I’m writing well: the goal is just to communicate ideas, after all, not to make art.
At the end of this article the author links to and mentions the four types of technical documentation: https://www.divio.com/blog/documentation/
I’ve found this to be especially useful when writing documentation. If you don’t think in this way them your documentation may end up being an impromptu blend of more than one type, and hence may not be useful for a specific use case. Instead I try to structure the documentation for one of these.
I’ve found this to be especially useful when writing documentation. If you don’t think in this way them your documentation may end up being an impromptu blend of more than one type, and hence may not be useful for a specific use case. Instead I try to structure the documentation for one of these.
These are great notes!
I’ve been writing for years, but I am constantly finding out that I still have a long way to go.
Thanks!
I’ve been writing for years, but I am constantly finding out that I still have a long way to go.
Thanks!
I recommend _Technical Editing: The Practical Guide For Editors And Writers_, https://www.amazon.com/Technical-Editing-Practical-Editors-H...
Thanks! I'll give it a look-see.
The third section advises to avoid meta writing. So... get rid of the first two paragraphs of this article?
Avoid meta writing when doing technical writing, not when writing about technical writing. It's already meta.
But this is a non-technical piece of writing about technical writing, not a piece of technical writing :)
It's not black or white like the author is suggesting, you need to give context in most cases which means a good introduction before jumping into the meat of the matter.
I wish tech writers would channel their focus elsewhere:
- If you haven't got it working, don't document it. Getting information by talking to SWEs is not enough. Your docs will lack depth and preciseness, and it will show. A lot.
- Show fully qualified imports in code samples. If you don't know what that is, ask SWEs. Given a computer with installed dependencies (such as Maven, Pip, npm, etc.), even your (grand)mother should be able to follow the docs.
- Create automated testsuide for your code samples.
- Mandate that lack of docs be a blocker for a release.
When there are docs written in perfect style and English, yet none of the code samples works, or when I have to spend 30 minutes finishing the "obvious" parts of the code to get it to work, that's when I get really frustrated.
The article seems to be deeply focused on the style. I can't remember when I got frustrated with documentation because the style was bad, or because the sentences were too long.