4 ms·

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.