> 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.
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.
Modern day software strives to do this, but regularly falls short. To craft the abstraction correctly, you need to understand how it is to be used—this is its “whole”. The person writing the internals of the abstraction who does not understand the whole writes the internals poorly. They create a feature that breaks expectations. They optimize a code path whose unoptimized implementation is relied on for one reason or another. The consumer of the code who does not understand the reasoning for these low level implementations starts relying on sub-behaviors that aren’t actually intended. This is why even the low level folks need to understand the (proximate, at least) whole.
What you’re describing is the lazy programming strategy that is certainly easier but results in dependency stacks that are brittle. It means you can plug a junior developer in anywhere without a mentor, but it also means QA efforts are enormous or breakage frequent. In UIs, it’s how Apple can rewrite applications in a new framework and lose decades of system behaviors because no one fully understood the whole when they replaced the abstraction.
Abstractions are leaky. It is in their nature. Understanding or describing how they are meant to be used makes the leakiness a little more obvious, a little easier to understand. Any given team can choose to be lazy about this of course, and will export the costs to their code’s consumers.
The output of a single individual may lack this context, of course. That is why the best abstractions are often created by teams over time: it takes skill in both typing code and devising and describing architecture to create a good tool in the form of an abstraction. It takes those same skills to achieve continuity over time in maintaining a given framework, application, or other abstraction. Documentation is an assist to the tribal knowledge that helps support this continuity, and a way to export that knowledge to new people, and try to make it outlast the original designers if the abstraction.
Yes, of course, when working on a piece of code (a low-level task), one should know where it sits within the bigger system. One needs to know all kinds of things about what lives both upstream and downstream, as well as some high-level architecture of the system as a whole. But the implication above (which I disagreed with) was that "good coding skills" (and thus a filter during hiring) implied "good documentation skills" does not follow from any of that.
Again: Code is always "low-level" (regardless of how much you do or don't know about the rest of the system) just like most API documentation. The complaint of the original article wasn't about API documentation, but about higher-level conceptual documentation being lacking. And just like not all "coders" may be able to design a large and complex system (though they may certainly be able to understand it) they also may be unable to document those high-level conceptual aspects of the system.
> you don't need to see how your code fits into the whole.
GP said a whole, not the whole.
A subsystem, abstraction, or whatever, works as a whole, not as unconnected pieces, and the code needs to reflect the organization and concepts within itself as a meaningful whole.
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.
It is mainly geared toward MacOS development but there is a section specifically about iOS for things like Audio Session. You will probably still need to keep the Apple docs open for iOS specific stuff here and there but in general the book does a GREAT job of bridging audio theory, with apple's architectural decisions, with low level implementation details. IMO thats the great strength of books, they tie it all together and this one - for me at least - checked all the boxes.
I've found that the higher-level docs often don't even need to be writing per se. I'd stick things like the 3-5 minute overview video, 30-60 minute presentations, and code examples in this type of category.
Who maintains these? Most development teams I've met never bother checking the example code works. 99% of the time, they'll write up a presentation, once, click "record" on the video conferencing software, and everyone says "cool, it's documented". And then, 6 months later, half the presentation is obsolete, and it ends up being even more confusing because as the reader, you have to investigate what has changed since this presentation happened.
I've noticed, if you put some real thought behind maintaining these higher level docs, you don't end up with _tons_ of documentation. And the speed of adoption is rapid. But it takes design, a feedback loop, etc. It's really another kind of deliverable, separate from creating a software product itself.
It's best to have documentation in a variety of communication formats. I cannot learn by watching a video as well as I can by reading, but everyone is different. If the only, or primary, documentation for your product or code is a video, I'm likely to pass on it unless there are no other choices.
Extraordinarily strongly disagree. Documentation should be first, best, and most thorough in written form. It is easily searchable, easily transferred, easily scanned for relevant sections.
Do anything else you want for your audienc3, but for me personally if there is not textual documentation, I will consider your system, software, library or whatever effectively undocumented.
I didn't say documentation shouldn't be written; writing is just one of many media types.
Many people do not stay focused with longer formats in writing. So adopting a variety of media is a good idea, especially for the fuzzier "conceptual" documents, as opposed to reference documentation.
And I say this as someone who prefers books. I've made the mistake of only using writing, and noticed about half of the team just never seemed to grasp the concepts. Example projects with really short videos helped them a lot.
You can't rely on documentation to be correct because, like comments, it can't be tested or automatically updated. It's only going to be reliable if the system under it never changes.
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.
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.
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.
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...
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.
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.
I completely agree. Of the various coders I've worked with over my career, I've noticed an astounding correlation between quality-of-writing and quality of code.
It becomes most curious with exceptionally talented people who are terrible communicators - they can engage with exotic and difficult pieces of code, but almost everything they write ends up being a trainwreck that nobody dares to use, nobody understands, and is typically riddled with bugs. Code is built to be used, and at the very least, you have to hand it off to other developers, or you're stuck maintaining it yourself. (In several cases like this, I've seen one of these programmers hand something off, and have others basically struggle to use it, and work around that by writing something much more rudimentary to replace it.)
I feel like a programmer needs to understand writing for the same reason a general needs to understand what it's like to be on the front line - even if they're doing very little of it themselves, they need a clear understanding of what needs to be accomplished and what the difficulties will be.
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.
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.
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.
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.
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).
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.
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.