> The most underrated skill to learn as an engineer is how to document. Fuck, someone please teach me how to write good documentation. Seriously, if there's any recommendations, I'd seriously pay for a course (like probably a lot of money, maybe 1k for a course if it guaranteed that I could write good docs.)
I agree but think it is more than just _documentation_: effectively communicating ideas through text was one of the most underrated skills in software engineering. I say "was" as I think there is much more focus on it now with remote work and video call fatigue becoming the norm for many.
I would suggest you avoid thinking in too general of terms like this. There are dozens of kinds of docs. It's better to think about the document's specific purpose, audience, what you need to convey, what the audience wants to know, and how they want to absorb it. Then write, then read it as that intended audience, see if that person can make sense of it, and if it provides enough information. If you can't put yourself in their shoes, have the audience proofread it.
Two important lessons I learned:
1. Formatting and direct communication is very useful. It can make the difference between someone stopping and noticing critical information, or skipping it because they're lazy readers.
2. You probably don't know the correct way to convey information, and the audience probably doesn't know how to tell you how to convey it either. You need to listen for when the docs fail: when somebody says they read the docs but still don't know something or don't do something right. That means your doc has a "bug" in how it gets through to the reader. Experiment, change things around, add/remove information, etc until the bug is gone.
Agree with the sibling comment, but a starting point is also just to write docs for your future self, which is usually going to be type 3 or 4. Most of us who have been programming for a few years have had the experience of being mystified by something we ourselves wrote in the past, so it eventually becomes fairly straightforward to predict what kinds of things future-me will need a hand in piecing back together.
And it turns out those kinds of docs are pretty useful to my colleagues in piecing it together also.
In contrast to the current sibling replies, I think this is a very fitting categorization of documentation. Off the top of my head, I can think of several examples where one type of documentation is excellent but others are very lacking, for example:
* Rust Library Documentation: Most libraries have complete and up-to-date reference documentation, but are lacking even basic introductions (tutorials/guides) on how to use the library. This is totally just my personal experience so maybe I've been looking at the wrong crates, but with most of the crates I spend several minutes looking trough all the modules in order to find that all the juicy functions are hidden in the Connection struct, or something similar.
* Linux Kernel Documentation: The Linux kernel has excellent in-depth explanations on several high-level concepts, but on the other hand a little more systematic reference documentation on the supporting library code would help a lot.
* While I can't think of a good example right now, a lot of projects have a few basic getting-started tutorials but don't explain advanced concepts or high-level design at all, leaving you to wade through the sources yourself in order to understand how to actually use them.
I end up reading the source half the time, anyway; documentation is often incomplete, dated, and possibly incorrect. For code, I'd prefer the time go into designing a cleaner interface and making what calls do obvious.
That said, I find high-level documentation for larger systems to be very valuable. I also find Python's docs to be lacking compared to Java's; I'm often left wondering about the definition of what type is returned, exactly what parameters should be, and which exceptions are raised. Java's docs are very explicit about all these things.
Thoroughly commented code tends to end up a couple changes out of date. A separate file in the same directory ends up a couple major refactors out of date. A separate file in a separate system ends up a couple company-wide reorgs out of date.
I agree. I'd like my documents to contain overview, intent, and exceptions. The actual implementation I can look up in the code. Also generated stuff is appreciated, like Swagger.
You should be reading the source all of the time. The point of documentation is to tell you what the code doesn't. If it tells you the same, you should delete the documentation.
That's useful, but only covers documenting the code, and API usage.
Depending on the project, various other documents may be required, e.g. installation guide, user guide, operations manual, architecture diagrams, networking diagrams, module/component diagrams, information flow diagrams, high-level design, low-level design, docs at various "views" (such as "business view", "information view", "technology view"), design decision tracker, ontology...
I'm actually in the middle of using Postman to generate a more "modern" inline docset for a new engineer that is coming into a project that uses that server.
One can hope, but sadly I don't think it's going to be an easy shift.
People managing work, from what I've seen, still prefer to babble over their scribbled 5 basic points than taking the time to do their job and create relevant textual information. Then you listen, you take notes, and then you go and produce whatever documentation of the objective is required to at least understand if it's going to work. Of course you still will have gaps in your understanding, so then more calls, and repeat. In the end, unnecessary/missing features, a whole bunch of time wasted in crap, deadlines missed, burnt time, all of which could have been avoided if someone just had taken the time to do their supposed job - this is not to say it wouldn't have to be discussed, or that there's no need for back and forth and calls, etc, it's just instead of starting halfway you start from -50% or something.
Even in outsourcing platforms there's been a shift contrary to that. At least two years ago and before that, video calls or calls weren't really usual unless you were in some months long collaboration - now even there everyone expects video calls on the interview... It doesn't matter if it's a $100 one time job or whatever.
Also "if the code is clear, it documents itself". Which in my opinion completely misses the point. Good documentation doesn't tell you what the code is doing, it tells you why it's not doing something else.
We had a guy that always opened PRs with no description. Guy always said “read the code”. Manager wouldn’t do shit and he kept doing it until we all just stopped reviewing his code and then he couldn’t merge.
Like dude, tell us why we should read the code in the first place.
Exactly. That's not a documentation problem, that's a writing problem. A lot of tech people don't enjoy writing, but also they're sometimes not very good at predicting or empathizing with the future reader of their writing. Sometimes that's also manifested in speaking, and failing to context frame concepts, arguments and ideas before jumping into excruciating detail. Senior managers notice this, and this limits your career.
So I argue that the issue is writing skills, of which technical documentation is a subset speciality of writing skills. I will add, similar to math problems or programming, writing wants you to do it over and over so it can get better.
> A lot of tech people don't enjoy writing, but also they're sometimes not very good at predicting or empathizing with the future reader of their writing.
Agreed, wholeheartedly. Will hitchhike on your comment to recommend two things: Brett Victor's pdf stash [1] and, specifically, the Walter Ong essay "The Writer's Audience is Always a Fiction"[2].
Long story short, we form our audiences by subjecting them to our writing. In writing software documentation, we are implicitly informing the next generation's thought by the simple power dynamic that underlies all technical documentation: "you must understand this in order to do your job properly".
It is no wonder that "form", "inform", and "information" are such closely related words.
We dictate the level of rigor and intelligibility we expect out of our technical documentation, when we write technical documents. It almost sounds like a tautology when put this way, but "bad docs" are exclusively the result of a professional culture that puts up with the existence of bad docs. I've been there; too tired and overworked to care about writing something properly, or wanting to avoid writing a doc enough that I setup some autodoc thing and called it a day. We literally don't get paid for writing documentation.
But good documentation is what made us into good developers (if we are good developers). We should get paid for doing that...
> effectively communicating ideas through text was one of the most underrated skills in software engineering
Absolutely. So many hour long meetings could be shortened by better communication skills (just more targeted), or even a small email chain.
Communicating in short form confidently is a skill. Many people, including myself (something I've been working on) struggle with saying something that was a complete idea in a meeting and not stopping because they feel like they need to say more. Short and sweet is the way to go pretty much whenever you can, for technical work that is.
And many many people don't do it well. On both ends. Reading is a skill too.
I find 'small email chains' don't help at all. Too many people just don't read past the first sentence or paragraph. And email is slow.
I usually 'escalate' quickly. Support didn't understand a ticket comment I made on how this isn't a bug or why there really is a workaround for it?
I send them an IM trying to coax it out of them/get them to understand for a few minutes. Doesn't work? Quick call and do screen sharing. Problem usually solved after a few minutes. Problem is they might stay longer than that took just to 'catch up' ;)
This is really not that different from when we were all at the office just that the last part would be walking over to their office and looking at the computer together. In some situations that makes it even easier nowadays because I don't need to take an elevator down 20 stories and back up again after.
Having asynchronous means of communication is great. But as soon as the back and forth is more than maybe twice on each side, there's probably a miscommunication happening somehow that will be much easier to get solved with a really short feedback loop. Some people you have to call right away coz they just type soooooo slowly ;)
Not only in writing but also in plain English.
I see situations like described below over and over.
Example 1 - too much details.
Morning stand up.
Manager: what's the status of that new feature.
Senior Engineer: well I tried to call that service but it was timing out so I spoke to Bob and he said to check with DBA on why that stored procedure but it's so slow and turns out index is missing so we tried to add it but mysql and varchar something fckn something...
Dude couldn't you just tell it's delayed due to DB and then expand if needed.
Example 2 - insufficient details
I return from the meeting and discover avalanche of emails, chat messages and urgent meeting invite, all with same topic - "Blah service fails, we are blocked" but no details apart from that. On the call I get description of the problem - blah service fails and how everyone is blocked and how infinitely critical it is and what ETA for resolution would be.
What endpoint? How does it fail - timeout, connection aborted, 503 response, 200 response but with error message?
I like documentation that starts with a minimal but functional example, followed by the most common additions to improve the solution and finally a complete documentation of all functions.
Having links to actual code, like GoDocs have it, is something I appreciate too.
Effective communicating is a crucial part of every job. I think in software engineering, a lot of us are introverts who want to deprioritize this soft skill, but the truth is still that people matter more than the code.
And communicating gets even more important the higher up you move in your seniority.
Documentation can also be anything. Is it your initial RFC or ADR, or is it a spec? Is it a set of product requirements? Is it inline with your code so it produces a manual when you build it? Is it a set of articles or tutorials written after the fact? Is it a README?
Effectively communicating through text amplified due to WFH. If you can avoid syncing up on video chat and resolve something with a couple of back and forth messages. That's a win
I find documentation to be relatively straightforward to write. The issue for me is sitting down and slogging through the activity, which seems almost antithetical to writing code. It's like doubling the work in a far less rewarding way. And then you have to go back and update it any time the code changes. It's a sort of necessary evil I suppose...I think most of the problem is that devs just can't be fucked to take the time, and I'm often guilty.
I agree but think it is more than just _documentation_: effectively communicating ideas through text was one of the most underrated skills in software engineering. I say "was" as I think there is much more focus on it now with remote work and video call fatigue becoming the norm for many.