7 ms·

> That’s not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code. Strong disagree on that one.

by m12k 5y ago

> That’s not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code. Strong disagree on that one. Writing good code is all communication - with the computer, with your colleagues, with your future self who doesn't remember how or why you did something. It's written knowledge transfer. Blocks of code, just like paragraphs of documentation, need to both fit into a whole, and be as accessible as possible on their own to someone jumping straight into them (e.g. someone straight from google, someone jumping in to do a quick bugfix or merge fix). The list goes on and on.

jtdev 5y ago
A good coder does not a good technical document writer make.
- bombcar 5y ago
  They can coincide in the same person - perhaps Donald Knuth’s form of literate code would be an example - but they’re independent skill sets. And for documentation to truly excel in needs to go far beyond “I transliterated the code into English” or even “here’s all the ways this API can be called” and far into the “here’s how to do what you want and here’s what you didn’t know you wanted.” That last part is often the most missing - documentation that educates and informs on all the new options not just the new ways of doing old things - of which Inside Macintosh is a great example.
- hug 5y ago
  I don't know why this is downvoted -- it's true. They are two very very different skillsets. I'm an ops guy, not a developer, and willing to hold my hand up and say that I suck at documentation. It's a deficit I recognise and work around: I have often paired up with someone who is better at documentation than I am, but less technically apt or possibly earlier on in their career than I am, because it's easier for me to tie a training piece along with the documentation piece. It's kinda like a win-win. If I didn't do this, generally nothing I did would be well documented. I can write what I think is decent documentation, but I find it tedious and tend to half-ass it. My bad. But that's not even the worst of it. The worst of it is that there are technical document writers in my line of work and the documents that they produce are an order of magnitude more useful and thorough than the best of my documentation. Like you could ask me to spend a week writing a document and them to spend a day and I'd be outclassed. It's a world of difference. I know some guys who are good devs and good technical document writers. I know some who are incredible at one and bad at the other. One human can have two differentiated skills, it's true, but they're not at all intrinsically tied. A good coder does not a good technical document writer make.
  - nemetroid 5y ago
    I haven't downvoted any comment in this thread, but I think the parent post was a low-effort oneliner that didn't touch on the arguments made by the comment it responded to, and as such doesn't meaningfully add the conversation (even if it were correct).
  - phlakaton 5y ago
    You seem to have the writing chops to be a great documentation writer. What is holding you back?
- rleigh 5y ago
  I disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer. Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit greatly from. Writing code is only one part of the job, and writing documentation, requirements and design is a big part of the rest, and these parts are just as important. It's often the case that the act of writing down these things identifies inconsistencies and omissions which have not been picked up on during design or code review. And, ultimately, your libraries or application need to be used by other people, and if it isn't properly documented it's going to fall short of expectations since people won't be able to use it as intended.
  - Spooky23 5y ago
    That’s a fair point, but good technical writing is a skill in of itself. Just like having dedicated UX SMEs on a team improves a product, technical writers do the same, especially for complex systems. It’s not that a software engineer isn’t capable of writing, but more that it’s not their primary responsibility. I also anecdotally believe that having people in roles like this who are accountable for documentation, design, etc improve the overall product as they provide another layer of review.
  - valuearb 5y ago
    Good technical documentation needs dedicated technical writers. Comments and internal docs can be handled by the engineers themselves, but turning that into an organized and properly formatted manual in a consistent style and voice for outside consumption is a specialized task that can’t be done piecemeal by the same people writing the code.
  - lanstin 5y ago
    I sort of think this except I had a job for several years where we had really good technical writers who would sit with various developer and produce far more accessible writing than I ever have. It is valuable for my career to be able to write somewhat well but I am hired and earn my salary in other ways, debugging weird technical things; two days experiments, code reading, and maybe gdb and then one small PR and a short email explaining the issue. Write some nice network server to solve a network issue; implement some feature in a maintainable way. Etc. lot of work and mostly the way of thinking about it is a small piece of that work. The tech writers made a small book that could be handed and/or emailed to people who then integrated with my API with no further interaction between me and them. It was very helpful.
Benjamin_Dobell 5y ago
I believe it depends who the target audience is for the documentation. Writing good documentation requires empathy. Writing good code does also. However, it's in general more difficult to empathise with someone who has a fundamentally different background than yourself. Some developers can write code other developers on their team will easily understand, but they're not necessarily able to understand the way less technically inclined individuals (or individuals with a different expertise) think. Generally speaking, this is why UX is such an important field. Writing good documentation is about understanding the target audience, and being able to understand the user's journey - which may be very different than your own.
adambatkin 5y ago
No. Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point of building abstractions, because it's too hard to keep all of the details in your head at one time. Writing code is generally concerned with the low-level details, which are hidden from other parts of the system (and that's a good thing). When you ask someone a coding question, that's what you are testing. To the point of the article, yeah maybe there is some correlation between someone who is good at writing code and good at writing API documentation. The complaint in the article is that the high-level conceptual documentation is lacking. The systems design stuff. The architecture. And while there are certainly people who are good at writing low-level code as well as understanding high-level architecture, that's not always true, as they are very different skillets (and I don't mean this as a slight against anyone, it's probable that most people who are good at one could become good at the other, but in practice, many people's jobs lead them to spend more time on one instead of the other, so that's where they build up skills and experience). Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book (as opposed to API documentation which is more like a dictionary or encyclopedia). You need to be able to pull information together from lots of places, and it must be presented in a methodical way, where (for example) you can't assume that the reader has knowledge of something before you have presented it.
- millerm 5y ago
  +1 Nicely explained.
- rubicon33 5y ago
  > Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book Totally agree. When I need to learn a new subject like Core Audio or something I get a book.
  - jamil7 5y ago
    A bit off topic but do you have any recommendations for learning Core Audio? Last time I was reading old blog posts and header files to do what I needed.
thesuperbigfrog 5y ago
Apple's issue is that unless the code is open source, the documentation is the only thing available to the "outside of Apple" audience. If the documentation for the "outside of Apple" audience is not good enough without access to the source code, then developers feel it and the overall result is that Apple suffers as a platform.
- TheOtherHobbes 5y ago
  Apple's issue is it doesn't seem to care. I'm going to speculate that improving the developer experience has a low status on the management hierarchy. So even if some people do care they're clearly not being given the resources to do anything about it. And the resources required are tiny. Technical writers are cheaper than developers, and you could hire a top team for $1m a year. Doubling that would still be a rounding error in Apple's revenue stream. Multiplying it by 10 and introducing good management would be enough to make Apple's dev docs world-beating and legendary. Apple could also run developer classes and camps online and f2f, publish its own books, create a regular stream of developer newsletters and tech updates, run forums that are actually useful, and so on. The fact that none of this is happening at scale is... unfortunate. WWDC is a small plug in a big hole, and doesn't come close to meeting the community's needs.
  - astrange 5y ago
    Everyone is pretty expensive when they have to live in Silicon Valley - even if not, anyone who interacts with engineers becomes nearly as expensive due to cost disease. There are other factors preventing improving it, because documenting a new project is effectively adding more people to the project team (even if they're "just" writers) and they still need to learn it by talking to the developers, who might not have the time, so it's not scalable. Third-party documentation scales by not being able to talk to those people and instead reverse engineering everything, but that would lead to embarrassing incorrectness if it was the first-party approach.
  - psahgal 5y ago
    I came to the same realization that Apple doesn't seem to care when I started learning how to build apps on iOS. Coming from Android, I was used to having high level conceptual guides on the core building blocks of the framework. In the Android docs, I found detailed explanations of Activities, Fragments, Views, and other major components. It was relatively easy for me to get started, and the system was designed to be extensible. Google even published blog posts regularly, which I could use to learn more about design decisions. When I made the jump to iOS, though, it was difficult to find parallel documentation for what I was looking for. At the time (this was 2015, mind you), I couldn't find anything beyond API documentation for ViewControllers, Views, Core Data, etc. Most of the major documentation existed on third-party sites like NSHipster. Not to mention code signing. I'm pretty sure I'm one of handful developers at my firm who knows the system well enough to explain how it works...and that was after 2 years of working in iOS full-time. I doubt that Apple will prioritize the developer experience on their platform anytime soon. Edit: In case anyone wants to see the difference... - Google's guide on Activities: https://developer.android.com/guide/components/activities/intro-activities https://developer.android.com/guide/components/activities/in... - Apple's guide on View Controllers: https://developer.apple.com/documentation/uikit/view_controllers https://developer.apple.com/documentation/uikit/view_control...
xwdv 5y ago
Disagree. The difference between professional technical documentation and something a “good coder” whipped up to explain some code is astounding. The skills to write good documentation approach something more resembling an English major than a programmer.
- runlevel1 5y ago
  I think it's more about being able to see things from the audience's perspective. It's hard to write good documentation without being able to visualize: - What they know - What they don't know - What they're probably trying to accomplish Some of the best API documentation comes in the form of examples, which doesn't draw much on writing skills. That said, explaining high-level concepts/theory does require writing skills, but it also requires the skills described above.

by m12k 5y ago

jtdev 5y ago

A good coder does not a good technical document writer make.

bombcar 5y ago
They can coincide in the same person - perhaps Donald Knuth’s form of literate code would be an example - but they’re independent skill sets. And for documentation to truly excel in needs to go far beyond “I transliterated the code into English” or even “here’s all the ways this API can be called” and far into the “here’s how to do what you want and here’s what you didn’t know you wanted.” That last part is often the most missing - documentation that educates and informs on all the new options not just the new ways of doing old things - of which Inside Macintosh is a great example.
hug 5y ago
I don't know why this is downvoted -- it's true. They are two very very different skillsets. I'm an ops guy, not a developer, and willing to hold my hand up and say that I suck at documentation. It's a deficit I recognise and work around: I have often paired up with someone who is better at documentation than I am, but less technically apt or possibly earlier on in their career than I am, because it's easier for me to tie a training piece along with the documentation piece. It's kinda like a win-win. If I didn't do this, generally nothing I did would be well documented. I can write what I think is decent documentation, but I find it tedious and tend to half-ass it. My bad. But that's not even the worst of it. The worst of it is that there are technical document writers in my line of work and the documents that they produce are an order of magnitude more useful and thorough than the best of my documentation. Like you could ask me to spend a week writing a document and them to spend a day and I'd be outclassed. It's a world of difference. I know some guys who are good devs and good technical document writers. I know some who are incredible at one and bad at the other. One human can have two differentiated skills, it's true, but they're not at all intrinsically tied. A good coder does not a good technical document writer make.
- nemetroid 5y ago
  I haven't downvoted any comment in this thread, but I think the parent post was a low-effort oneliner that didn't touch on the arguments made by the comment it responded to, and as such doesn't meaningfully add the conversation (even if it were correct).
- phlakaton 5y ago
  You seem to have the writing chops to be a great documentation writer. What is holding you back?
rleigh 5y ago
I disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer. Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit greatly from. Writing code is only one part of the job, and writing documentation, requirements and design is a big part of the rest, and these parts are just as important. It's often the case that the act of writing down these things identifies inconsistencies and omissions which have not been picked up on during design or code review. And, ultimately, your libraries or application need to be used by other people, and if it isn't properly documented it's going to fall short of expectations since people won't be able to use it as intended.
- Spooky23 5y ago
  That’s a fair point, but good technical writing is a skill in of itself. Just like having dedicated UX SMEs on a team improves a product, technical writers do the same, especially for complex systems. It’s not that a software engineer isn’t capable of writing, but more that it’s not their primary responsibility. I also anecdotally believe that having people in roles like this who are accountable for documentation, design, etc improve the overall product as they provide another layer of review.
- valuearb 5y ago
  Good technical documentation needs dedicated technical writers. Comments and internal docs can be handled by the engineers themselves, but turning that into an organized and properly formatted manual in a consistent style and voice for outside consumption is a specialized task that can’t be done piecemeal by the same people writing the code.
- lanstin 5y ago
  I sort of think this except I had a job for several years where we had really good technical writers who would sit with various developer and produce far more accessible writing than I ever have. It is valuable for my career to be able to write somewhat well but I am hired and earn my salary in other ways, debugging weird technical things; two days experiments, code reading, and maybe gdb and then one small PR and a short email explaining the issue. Write some nice network server to solve a network issue; implement some feature in a maintainable way. Etc. lot of work and mostly the way of thinking about it is a small piece of that work. The tech writers made a small book that could be handed and/or emailed to people who then integrated with my API with no further interaction between me and them. It was very helpful.

Benjamin_Dobell 5y ago

I believe it depends who the target audience is for the documentation. Writing good documentation requires empathy. Writing good code does also. However, it's in general more difficult to empathise with someone who has a fundamentally different background than yourself. Some developers can write code other developers on their team will easily understand, but they're not necessarily able to understand the way less technically inclined individuals (or individuals with a different expertise) think. Generally speaking, this is why UX is such an important field. Writing good documentation is about understanding the target audience, and being able to understand the user's journey - which may be very different than your own.

adambatkin 5y ago

No. Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point of building abstractions, because it's too hard to keep all of the details in your head at one time. Writing code is generally concerned with the low-level details, which are hidden from other parts of the system (and that's a good thing). When you ask someone a coding question, that's what you are testing. To the point of the article, yeah maybe there is some correlation between someone who is good at writing code and good at writing API documentation. The complaint in the article is that the high-level conceptual documentation is lacking. The systems design stuff. The architecture. And while there are certainly people who are good at writing low-level code as well as understanding high-level architecture, that's not always true, as they are very different skillets (and I don't mean this as a slight against anyone, it's probable that most people who are good at one could become good at the other, but in practice, many people's jobs lead them to spend more time on one instead of the other, so that's where they build up skills and experience). Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book (as opposed to API documentation which is more like a dictionary or encyclopedia). You need to be able to pull information together from lots of places, and it must be presented in a methodical way, where (for example) you can't assume that the reader has knowledge of something before you have presented it.

millerm 5y ago
+1 Nicely explained.
rubicon33 5y ago
> Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book Totally agree. When I need to learn a new subject like Core Audio or something I get a book.
- jamil7 5y ago
  A bit off topic but do you have any recommendations for learning Core Audio? Last time I was reading old blog posts and header files to do what I needed.

thesuperbigfrog 5y ago

Apple's issue is that unless the code is open source, the documentation is the only thing available to the "outside of Apple" audience. If the documentation for the "outside of Apple" audience is not good enough without access to the source code, then developers feel it and the overall result is that Apple suffers as a platform.

TheOtherHobbes 5y ago
Apple's issue is it doesn't seem to care. I'm going to speculate that improving the developer experience has a low status on the management hierarchy. So even if some people do care they're clearly not being given the resources to do anything about it. And the resources required are tiny. Technical writers are cheaper than developers, and you could hire a top team for $1m a year. Doubling that would still be a rounding error in Apple's revenue stream. Multiplying it by 10 and introducing good management would be enough to make Apple's dev docs world-beating and legendary. Apple could also run developer classes and camps online and f2f, publish its own books, create a regular stream of developer newsletters and tech updates, run forums that are actually useful, and so on. The fact that none of this is happening at scale is... unfortunate. WWDC is a small plug in a big hole, and doesn't come close to meeting the community's needs.
- astrange 5y ago
  Everyone is pretty expensive when they have to live in Silicon Valley - even if not, anyone who interacts with engineers becomes nearly as expensive due to cost disease. There are other factors preventing improving it, because documenting a new project is effectively adding more people to the project team (even if they're "just" writers) and they still need to learn it by talking to the developers, who might not have the time, so it's not scalable. Third-party documentation scales by not being able to talk to those people and instead reverse engineering everything, but that would lead to embarrassing incorrectness if it was the first-party approach.
- psahgal 5y ago
  I came to the same realization that Apple doesn't seem to care when I started learning how to build apps on iOS. Coming from Android, I was used to having high level conceptual guides on the core building blocks of the framework. In the Android docs, I found detailed explanations of Activities, Fragments, Views, and other major components. It was relatively easy for me to get started, and the system was designed to be extensible. Google even published blog posts regularly, which I could use to learn more about design decisions. When I made the jump to iOS, though, it was difficult to find parallel documentation for what I was looking for. At the time (this was 2015, mind you), I couldn't find anything beyond API documentation for ViewControllers, Views, Core Data, etc. Most of the major documentation existed on third-party sites like NSHipster. Not to mention code signing. I'm pretty sure I'm one of handful developers at my firm who knows the system well enough to explain how it works...and that was after 2 years of working in iOS full-time. I doubt that Apple will prioritize the developer experience on their platform anytime soon. Edit: In case anyone wants to see the difference... - Google's guide on Activities: https://developer.android.com/guide/components/activities/intro-activities https://developer.android.com/guide/components/activities/in... - Apple's guide on View Controllers: https://developer.apple.com/documentation/uikit/view_controllers https://developer.apple.com/documentation/uikit/view_control...

xwdv 5y ago

Disagree. The difference between professional technical documentation and something a “good coder” whipped up to explain some code is astounding. The skills to write good documentation approach something more resembling an English major than a programmer.

runlevel1 5y ago
I think it's more about being able to see things from the audience's perspective. It's hard to write good documentation without being able to visualize: - What they know - What they don't know - What they're probably trying to accomplish Some of the best API documentation comes in the form of examples, which doesn't draw much on writing skills. That said, explaining high-level concepts/theory does require writing skills, but it also requires the skills described above.