Documentation is a feature, the rest of my comment is anecdotal but in many shops, it’s tracked as part of the task of coding. I’ve started making separate JIRA tasks to explicitly create or update the documentation and have told my team to do the same. So far, the results are good.
Documentation can be implicitly managed thorough writing clear, slightly verbose code with good comments, as well as clearly described test cases. It can also live in the project management tools if used effectively. With a good software development process you can have a historical record of the background, requirements, discussions around that feature/component, and how it was developed
your manager will never give you a raise because you wrote nice documentations, in fact, he/she might think you're wasting time for not doing bugfixes or features development.
as long as documentation of code becomes one factor to evaluate the developers, with rewards somehow, things will change immediately.
I never felt doc is a technical problem, it's purely management for this one, it has been neglected for too long.
Diataxis[1] (mentioned on here recently) and ADR[2] massively helped me to create clearer docs. The Diataxis framework really helps you create something that could bring a new developer on board quickly, and ADR helps ensure the thinking behind architecture decisions is easy to understand.
I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”.
I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons.
First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing and polishing documentation for hours. When the code inevitably changes, I can throw away the old video and spend another thirty minutes making a new one.
Second, I can demonstrate what the code does while offering instruction around it. If I likened it to anything, it’s like having a series of lectures to your code base rather than a textbook.
And lastly, it’s proven GREAT for on boarding a new engineer in the more complex aspects of the project. Because they can go and view thousands of PRs, 90% of which have video demonstrations or explanations, they can do a lot of self directed learning and not require nearly as much over the shoulder time with other engineers. When your team is spread across 12 hours of time zones, this is very useful.
This method isn’t a panacea, and we still keep written documentation when we need to provide a concise set of “how to’s” to other teams. But for the dev team, it’s been great.
Videos are also better at transfering tacit knowledge. Stuff like little habits and workarounds people have that are important but which they don't realize need to be communicated.
For example, creating a virtual environment for a python project instead of installing it globally. This is a crucial step for things to work well, but it's so common it might be left unstated.
With respect, you save time making 30 minute videos, but everyone else then wastes time watching your video looking for info.
I prefer it if people just write it down so I can ctrl-f or find it in a web search and get what I need instead of sitting through your videos.
For general "welcome to Team X!" onboarding or training though I agree that videos have benefits. But for day to day knowledge and docs I couldn't think of anything worse, although it seems to work for you and it is popular on YouTube for some things (e.g. Unity game dev content seems be be pretty much 100% video based - if I just need to know how to set up something in the UI like character rigging or wheel physics etc, I often have to sit through 30min videos to find the 15 seconds where they show what buttons to click etc - if it was on a web page I could just skip right to it)
I just love YouTube's automatic transcripts for this. Open, copy it into a text document so you can read it in a bigger window, then ctrl-f. You can skim it quickly to find the key point you're after. Sometimes things will be transcribed incorrectly but the surrounding context helps.
> Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly. While the expressing part can be simplified to some extent (depending on the quality of writing required), all three steps are taxing when done properly.
Wow, almost sounds like some other aspect of a job a software engineer is required to do...
> If a developer doesn’t write documentation, their work still gets done.
If documentation is part of their job, it literally does not.
> Not writing doesn’t block shipping (at least not right away).
the last is bs. if you dont ship you wont make money, the compaby dies. if you dont write docs, you might incur tech debt but the company keeps on living.
ofc if there is enough time and manpower: write docs, write unit tests, discuss architecture. no prob.
This was my attitude as well for much of my career, and it was a mistake. The "correct" decision depends on the state of the business and your resources at the time. And nothing else.
I don't know why you're getting downvoted. Tech debt is a tool and I think it's absolutely fair to put the needs of the business before documentation, or even code quality to a certain extent. As long as developers and management are aware that isn't free, and the cost must be repaid, I think it's the right decision in many cases.
Yes, I've worked mostly in money losing startups, but since I work in a $ billion-profit investment bank I saw the difference. It's better to waste money on technical debt crisis down the line than have no money to waste because of thousands of devs all being perfectionists locking each other.
Small startups seem to reach this stage eventually and in big companies, management is acutely aware of it, and breaks every attempt at correctness-over-business-rationality, under the teary cries of the autists, sometimes :D
I don't want to work for a company that puts its need above mine. That company isn't worth my energy.
The correct decision is to take an approach that involves producing quality code and documentation as you go.
If you don't have the time available to do that then you don't actually have the time to do that piece of work.
Doing so regardless, or becoming expeditors is the worst thing you can do for a company. It creates a race to the bottom which in turn creates a god awful place to work.
This feedback loop continues to worsen as you struggle to hire and struggle to retain.
> Wow, almost sounds like some other aspect of a job a software engineer is required to do...
Which I think is the real problem. Writing/modifying code can't be ignored; the resulting behavior of technical systems absolutely depends on doing that.
You can argue that the desired behavior of human system also depends on good writing and you're correct. But the connection of the input and output is much more opaque, the social conception of the role is focused on the behavior of technical systems, the incentive structures are therefore focused on the behavior of technical systems, so when there is more to do than can be done writing docs will not make the top of the priority queue.
Everywhere I’ve been except for IBM in the 90s, documentation is not given priority (time) as would be needed to both write the first round adequately and then maintain it as realities change.
Tools are much less a problem.
I suspect also that modern “agile” approaches work against building and maintaining documentation because developers are hyper focused on ticket level changes in short sprints.
Same goes to a lesser degree in writing tests. And when it comes to tests, devoting an entire sprint to increasing coverage seems to compensate, so perhaps a documentation sprint every few months might work.
Actually, the agile sprint approach also works against clean code based and discourages refactoring. So refactor sprints need to happen periodically.
I think I see a pattern here: current agile methodologies trade one set of problems for a new set.
It just requires time, and I would be happy to spend that time (I love writing, whether docs or just thoughts). As long as there's no ticket for it (approved by a stakeholder and assigned to me by the micromanager), I can't clock hours on it, and if I'm not clocking hours on a ticket, I'll eventually get an angry call..
It's not just lack of incentives, it's disincentives.
The problem with documentation is twofold:
1. it's broadcast-only. so you have to try to anticipate in advance what the questions might be.
2. it's disconnected from the source. so someone looking at the source code has no idea whether there is good, bad, or any documentation about it.
What if we don’t incentivize and it’s important? Further, what if we can improve it without incentivizing? My teams code is very well documented because we encourage documentation during code review. No one gets a bonus for this, but it doesn’t matter because we care about our softwares quality.
Put another way, good software bad doc is a lot harder and more costly than good software good doc.
That's just a negative incentive where you get punished if you don't write documentation.
It works. But it's hard to be consistent.
Let's say someone build a great feature with a lot of traction (e.g. money) but no doc.
Will you punish the team or celebrate the success?
"Sorry, your project make 20m, higher than any other projects in the company, but your doc is bad, so... you get below expectation rating this time".
There are tons of successful software with very little doc. So, my imaginary situation is very plausible. On the other hand, bad software with good doc rarely succeeds. But tbf bad software means unsuccessful software....
I've seen an awful lot of discussion of recruiting and interviewing practices on this site over the years, and there have been very few mentions of ways to check that people employed as programmers are able to write documentation.
Now you have one more problem (several, in fact) - explaining the business and the software to the technical writer. This is so difficult, that in all my long career in software development and management, I never saw any company specifically hire a technical writer, though I have done a lot of technical writing myself, on the side.
The technical writer can be involved in the release management and ask for details that then he can use as a starting point.
They can help identify gaps in documentation, outdated documentation, etc. They can take care of the clarity, formatting and distribution. You can create a ticket about documentation and assign it to them.
Then, while many developers write excellent documentation... some other developers truly SUCK at documenting. Some people like to sound intelligent and their comments read like a choose-your-adventure monologue that cannot be read linearly. Or they use vague, ambiguous language, or overuse acronyms or abbreviations. Or they sign every piece of code they touch like a dog scent marking your entire code base. Or they use profanity, or they get offtopic or humorous... All of that is a distraction from doing my job.
The technical writer takes care of those problems for you. They can create guidelines for documentation so that people treat documentation with the respect it deserves.
This is a terrible solution. Writing is part of the developers job requirements. And writing doesn't just happen in documentation. It happens in emails, technical specs, presentations, code comments. Developers should maybe just get better at their job because documenting and writing is part of it.
Writing is part of developer job requirements, sure.
Is technical writing part of your interviews? do you hire, promote or fire people based on technical writing performance? Is documentation taken as seriously as other code deliverables?
Why paying an expensive senior developer to maintain documentation in a non-commited way when you can pay a technical writer to do it better and for cheaper than the engineer can?
And with real ownership and accountability over documentation, unlike the engineers.
Technical writers are cost efficient and pay themselves very quickly.
I often see peers struggle with writing documentation because they prioritize it as a separate task. For example they write all the code in a giant PR and then try to go back and write the documentation for everything at once. This creates a much larger more insurmountable seeming goal than if they had broken up the task and written the docs for each piece instead.
Another critical mistake is expecting devs to cover writing the documentation that explains the deep contextual intricacies of the business logic and reasoning for said logic. Big mistake. Your docs should cover the code and how it can be operated. Anything else is why we have project briefs, strategies and other documents and meetings.
So writing documentation isn’t hard. It’s just more and more devs are coming from a willy-nilly-web-search-when-you-think-of-it background with no formal organizational skills or experience.
Most of what is written in doc-blocks above your function should be generated. Everything else is operational information.
The single biggest ROI I've seen on getting documentation written is to provide a template for developers to fill out.
Blank wiki pages are incredibly intimidating and developers can't always anticipate what people will want. Having a "madlib" style outline with things like:
- Where does this app run?
- How do you start it?
- Where are the logs?
- How do you common items X,Y,Z?
Takes your odds of documentation being written from near zero (in my experience) to at least 60%.
This. Some of the best documentation is a simple "getting started" guide that explains: How to build (any dependencies?), how to hook a debugger or access debug logs and some pointers to where to start when looking at code (example: set a breakpoint here and trigger this action, you'll end-up in X component and should be able to figure out what's going on from there).
The best documentation I ever saw in a product was written by actual technical writers that worked in collaboration with the developers. If you want fantastic documentation, make it someone’s full time job.
If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on, the software itself will have outlived its' usefulness. In an agile environment like this, keeping any kind of documentation up to date to be meaningfully useful is almost impossible without a dedicated team member.
And a good set of unit tests can also cover what's the most useful, like edge cases, complex sequence, particular client flows, bug that actually happened in prod etc
Writing is thinking and oftentimes just being able to explain in words what a thing does, should do, and should not do- has tremendous value as part of the design process before any code is written.
Documentation is not generally useless. Most code is used far longer than it's intended life, most code is read far more often than it's changed, and documentation can save literally hours and days of struggle. Word of mouth knowledge transfer is abysmal at keeping critical knowledge alive. Nobody ever knows anything about legacy code, and it's because no one wrote documentation. Please stop telling people documentation isn't important
I do agree that code is read more than it is written. At the same time, there's the adage: "treat your data as permanent, and your code as transitory."
Under this kind of plausible argument, lie all sort of insects (bugs) in the dark. If people can make time to write tests, so should they write documentation. There is inordinate amount of frustration, productivity loss, and regression associated with having poor/outdated/no documentation.
Not really. Maybe in your very narrow environment, but all the multinational corporations I've worked in past 17 years on, situation is way more complex. Software often outlives people who created them, sometimes even whole teams originally responsible for it.
Suddenly you have a Pune team managing all environments including production, who have rather vague about yet another system thrown on them due to that smart idea called outsourcing. Sure they can change a thing or two, but corner cases can and often do bite hard. Code itself, while describing well what is happening, often doesn't contain much info about why. Or further effects of decisions. Full picture of whole integration involving 20 or 100 systems etc...
Another issue in huge companies spread across the globe is the ability to actually connect with relevant team, and their reluctance to share crucial info. A job security political game is not foreign to devs in some cases. I've had my request for source code of one of our internal security libs, the cornerstone of all of our inter-app authentication, refused with justification that its safer for the company to not share it even within company. Mind you, the .jar wasn't obfluscated at all so JAD got me to almost-compilable version so that effort wasn't even half-assed.
Man, I could spend whole evening telling stories how documentation can be great. Even incomplete, not completely up-to-date one can save your ass from time to time. And tons of time on top of that.
Documentation is so important. The problem with documentation is that engineers don't seem to understand it's benefits. I think one reason is that so much of the documentation out there is so poor quality that engineers think documentation can't be good quality.
You are right! You said just what David Parnas keeps saying. People don't know what or how to document
because they weren't taught to do it. It's not common knowledge. One has to dig into reading books and papers just to get the idea that it is possible.
This article is a bit of a non sequitur. I generally agree with the points raised but the real problem is whether documentation is given enough time within the development cycle. In my experience it isn’t.
The point of documentation is to communicate to others how to keep developing a code base - what is does, how it does it etc. What form the documentation takes can be fluid, a full fledged wiki or a single readme.md file can fulfill the same role just as well! Some documentation is better than nothing, so start small and then improve it over time.
There's a common refrain that internal documentation never gets updated and so it's better to just look at the code. IMHO outdated docs are still better than no docs, you just have to approach them with an appropriate level of skepticism and archaeologist mindset. At the base level of course the code is the ultimate source of truth, and being able to navigate code history quickly (via something like the Fugitive vim plugin) is incredibly valuable, but higher levels of documentation such as code comments, commit messages, tech specs, product specs, and user documentation can give richer clues into the mindset of the team at the time. As such, I believe the single highest ROI thing you can do is to choose tools that automatically maintains history/edit timestamps for all docs (git obviously does this, but Google Docs and Quip also do quite well here).
> you just have to approach them with an appropriate level of skepticism and archaeologist mindset
The problem is most people don't have this mindset. They expect documentation to be right, and when it isn't, they become frustrated and learn to avoid documentation.
I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little information about why it is designed that way.
* Can be learned from the code: Function A accepts a C-style pointer to a data array.
* Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doing any memory allocation.
* Cannot be known from the code: Even though the data array is initialized to 0 in the current code, function A should not assume that will always be the case. That data array is intended to be used as persistent storage in a future version.
The first one is kind of pointless to document beyond what doxygen already gives you. The second is useful, but not necessary. The third is absolutely essential, because nothing in the current code can possibly tell you about the future intents for changes in the code.
* Cannot be known from the code: The intent to use the array as persistent storage in the future is driven by the ongoing work around feature F.
* Cannot be known from the code: Feature F morphed into feature Q, and the function A doesn't really need that array anymore. Since nobody could tell why it was there in the first place, nobody removed it afterwards.
The next time someone has to make changes to function A, they'll be thankful for a comment or commit message that explains the first point above - as it'll let them complete the picture and realize it's no longer needed, so they don't have to worry whether their change is impacting anything else in the program through (mis)use of that array, but they can instead just go ahead and delete it.
Because it's thankless. The bosses I've had generally seem to think that writing documentation beyond inline comments is a waste of time; something that shouldn't be done unless scheduled for. And of course it's always the first job to be postponed if the schedule is tight (it always is.)
At work, documentation gets written when the boss isn't looking. Corporate culture makes writing documentation taboo. The examples of great documentation I am most familiar with are written for open source projects where managers aren't around to hassle people for writing it. Particularly: mpv, ffmpeg, racket, emacs. In my career I have yet to encounter a commercial software project with documentation at this level.
I do both and it’s not hard, it’s work and people have gotten lazy and don’t do work anymore they just write and read BS on the net and call it true and vote people down for telling the truth.
Lazy people do the minimum amount of work required of them, not the easiest work. Generally, documentation is useful, not required or business critical
I think the answer is just to have more people in the loop. Why do I have to write code, tests, documentation, dealing with jira tickets etc... In the old days, people had secretaries to handle some tasks. I would gladly exchange lower pay for having more people to spread out these tasks.
If it was that easy, there would indeed be a silver bullet: Secretaries could write specs that would compile into magical code solving every problem. They'd also infer user tutorials and data flow diagrams from machine code, to help out fresh blood.
What people can do it help allievate the gaps, but sadly, they're not geeting much help from managers and business people this time 'round either.
So do I. I even write documentation for personal projects, as a manual to my future self. However, absolutely every team I've ever worked with held a majority view of documentation being unnecessary.
Some even mentioned "code as documentation". In the end, they just kept finding justifications for not writing documentation or even proper code comments.
Three months after some solution was written, they couldn't explain the thinking behind it or even all the deep dependencies and magic return values because the person who had written the solution had left the team. Even then they were unwilling to see how documentation would have helped.
This repeated with every freaking team I have ever worked with. The only documentation any of those projects had was the one I created while figuring out the code base.
I observed a fundamental laziness in written communication in many developers and to this day I find it puzzling. I sometimes write down a draft of some solution just by myself, like I would explain it to another developer. More often than not, this helps me in highlighting inconsistencies or errors in my thinking.
I can agree that writing documentation is certainly more boring than writing code, and lazyness tends to play a role in the willingness to complete boring tasks.
But there are many legitimate reasons why one would clarify it as "harder" than programming:
- It requires a different skillset, namely writing.
- It is not uncommon for non-english shops to have a policy of documentation in english. That might be sensible, but complicates the task even further.
- In programming, it suffers from the same problems as math: Natural language is more often than not unsuited to express entirely abstract concepts, at least in concise and easily understandable ways.
- Conversely, natural language often lacks the necessary precision to talk about technical details.
- To alleviate all these problems with language somewhat, you might opt to use diagrams. Which requires yet another skillset.
- It requires time. And quite a lot of it actually. Usually more than you need for the actual programming task. This is why most managers care way less about documentation than they should: They know very well that it detracts time from actual programming tasks.
So sure, people tend to be lazy, but there are certainly good reasons why that happens more often in this area of our work than in others.
152 comments
[ 2.7 ms ] story [ 134 ms ] threadyour manager will never give you a raise because you wrote nice documentations, in fact, he/she might think you're wasting time for not doing bugfixes or features development.
as long as documentation of code becomes one factor to evaluate the developers, with rewards somehow, things will change immediately.
I never felt doc is a technical problem, it's purely management for this one, it has been neglected for too long.
[1] https://diataxis.fr/ [2] https://adr.github.io/
I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons.
First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing and polishing documentation for hours. When the code inevitably changes, I can throw away the old video and spend another thirty minutes making a new one.
Second, I can demonstrate what the code does while offering instruction around it. If I likened it to anything, it’s like having a series of lectures to your code base rather than a textbook.
And lastly, it’s proven GREAT for on boarding a new engineer in the more complex aspects of the project. Because they can go and view thousands of PRs, 90% of which have video demonstrations or explanations, they can do a lot of self directed learning and not require nearly as much over the shoulder time with other engineers. When your team is spread across 12 hours of time zones, this is very useful.
This method isn’t a panacea, and we still keep written documentation when we need to provide a concise set of “how to’s” to other teams. But for the dev team, it’s been great.
For example, creating a virtual environment for a python project instead of installing it globally. This is a crucial step for things to work well, but it's so common it might be left unstated.
So, our company creates videos, no one except new people watches them and everybody complains about lack of documentation.
I've only done it once so far, but I created a short video with Loom to demonstrate how a bug could be caused in the PR that fixed it.
Searchability is probably what would suffer from this approach, and the fact that text is much easier to edit (both for succinctness and correctness).
I prefer it if people just write it down so I can ctrl-f or find it in a web search and get what I need instead of sitting through your videos.
For general "welcome to Team X!" onboarding or training though I agree that videos have benefits. But for day to day knowledge and docs I couldn't think of anything worse, although it seems to work for you and it is popular on YouTube for some things (e.g. Unity game dev content seems be be pretty much 100% video based - if I just need to know how to set up something in the UI like character rigging or wheel physics etc, I often have to sit through 30min videos to find the 15 seconds where they show what buttons to click etc - if it was on a web page I could just skip right to it)
Wow, almost sounds like some other aspect of a job a software engineer is required to do...
> If a developer doesn’t write documentation, their work still gets done.
If documentation is part of their job, it literally does not.
> Not writing doesn’t block shipping (at least not right away).
It should.
but for a lot of companies speed is king
Yes there are trade offs with everything you do in IT, one of them is creating a shit place to work in the name of speed.
It might work for a little while but eventually you're going to realize you're shitting where you eat.
Small startups seem to reach this stage eventually and in big companies, management is acutely aware of it, and breaks every attempt at correctness-over-business-rationality, under the teary cries of the autists, sometimes :D
Too much perfectionist? You will enjoy the journey, but probably won't reach your destination.
Til I realised it was a false dichotomy.
I don't want to work for a company that puts its need above mine. That company isn't worth my energy.
The correct decision is to take an approach that involves producing quality code and documentation as you go.
If you don't have the time available to do that then you don't actually have the time to do that piece of work.
Doing so regardless, or becoming expeditors is the worst thing you can do for a company. It creates a race to the bottom which in turn creates a god awful place to work.
This feedback loop continues to worsen as you struggle to hire and struggle to retain.
Eventually, you're fucking Comcast.
> It should.
Perhaps, but it doesn't.
>It should.
The rub is that it might not block what's currently being shipped. But that debt can come back to introduce headaches and delays for the next ship.
Which I think is the real problem. Writing/modifying code can't be ignored; the resulting behavior of technical systems absolutely depends on doing that.
You can argue that the desired behavior of human system also depends on good writing and you're correct. But the connection of the input and output is much more opaque, the social conception of the role is focused on the behavior of technical systems, the incentive structures are therefore focused on the behavior of technical systems, so when there is more to do than can be done writing docs will not make the top of the priority queue.
Tools are much less a problem.
I suspect also that modern “agile” approaches work against building and maintaining documentation because developers are hyper focused on ticket level changes in short sprints.
Same goes to a lesser degree in writing tests. And when it comes to tests, devoting an entire sprint to increasing coverage seems to compensate, so perhaps a documentation sprint every few months might work.
Actually, the agile sprint approach also works against clean code based and discourages refactoring. So refactor sprints need to happen periodically.
I think I see a pattern here: current agile methodologies trade one set of problems for a new set.
People still did not liked writing documentation. They still did not knew how to write it.
It just requires time, and I would be happy to spend that time (I love writing, whether docs or just thoughts). As long as there's no ticket for it (approved by a stakeholder and assigned to me by the micromanager), I can't clock hours on it, and if I'm not clocking hours on a ticket, I'll eventually get an angry call..
It's not just lack of incentives, it's disincentives.
Good software, bad doc is probably okay.
Bad software, good doc is downright bad.
Therefore, people/exec/management don't prioritize it.
If it were to be compensated with 100k, you would get the best doc ever.
We can't improve things if we don't incentivize. We don't incentivize because it's not that important.
Put another way, good software bad doc is a lot harder and more costly than good software good doc.
Totally agree with you otherwise.
It works. But it's hard to be consistent.
Let's say someone build a great feature with a lot of traction (e.g. money) but no doc.
Will you punish the team or celebrate the success?
"Sorry, your project make 20m, higher than any other projects in the company, but your doc is bad, so... you get below expectation rating this time".
There are tons of successful software with very little doc. So, my imaginary situation is very plausible. On the other hand, bad software with good doc rarely succeeds. But tbf bad software means unsuccessful software....
Not only for your external documentation... for all of it.
If you are afraid of the costs, do the math.
1 technical writer for every 20 developers.
They can help identify gaps in documentation, outdated documentation, etc. They can take care of the clarity, formatting and distribution. You can create a ticket about documentation and assign it to them.
Then, while many developers write excellent documentation... some other developers truly SUCK at documenting. Some people like to sound intelligent and their comments read like a choose-your-adventure monologue that cannot be read linearly. Or they use vague, ambiguous language, or overuse acronyms or abbreviations. Or they sign every piece of code they touch like a dog scent marking your entire code base. Or they use profanity, or they get offtopic or humorous... All of that is a distraction from doing my job.
The technical writer takes care of those problems for you. They can create guidelines for documentation so that people treat documentation with the respect it deserves.
> All of that is a distraction from doing my job.
What job would that be? Do you actually have one?
For privacy reasons as this is indexed in search engines and comments cannot be deleted after 1 hour, forever.
> What job would that be? Do you actually have one?
I do, and it's none of your business.
If you want to participate in a community with an expectation of real life identity go have your discussions on Facebook or whatever.
Is technical writing part of your interviews? do you hire, promote or fire people based on technical writing performance? Is documentation taken as seriously as other code deliverables?
Why paying an expensive senior developer to maintain documentation in a non-commited way when you can pay a technical writer to do it better and for cheaper than the engineer can? And with real ownership and accountability over documentation, unlike the engineers.
Technical writers are cost efficient and pay themselves very quickly.
Another critical mistake is expecting devs to cover writing the documentation that explains the deep contextual intricacies of the business logic and reasoning for said logic. Big mistake. Your docs should cover the code and how it can be operated. Anything else is why we have project briefs, strategies and other documents and meetings.
So writing documentation isn’t hard. It’s just more and more devs are coming from a willy-nilly-web-search-when-you-think-of-it background with no formal organizational skills or experience.
Most of what is written in doc-blocks above your function should be generated. Everything else is operational information.
The single biggest ROI I've seen on getting documentation written is to provide a template for developers to fill out.
Blank wiki pages are incredibly intimidating and developers can't always anticipate what people will want. Having a "madlib" style outline with things like:
- Where does this app run?
- How do you start it?
- Where are the logs?
- How do you common items X,Y,Z?
Takes your odds of documentation being written from near zero (in my experience) to at least 60%.
Who needs it?
what needs to be done?
who is the subject matter expert?
and so on. This makes it easier for the developer working on the task, keeps the description short and sweet.
If you're building an open source general purpose tool, or something else meant to be reusable and consumed by the general public then sure. But the vast majority of software we write has a very definite lifecycle of birth, maintenance, and death. For the most part, one team with continuous word of mouth knowledge transfer will be responsible for it. And by the time that team has moved on, the software itself will have outlived its' usefulness. In an agile environment like this, keeping any kind of documentation up to date to be meaningfully useful is almost impossible without a dedicated team member.
Suddenly you have a Pune team managing all environments including production, who have rather vague about yet another system thrown on them due to that smart idea called outsourcing. Sure they can change a thing or two, but corner cases can and often do bite hard. Code itself, while describing well what is happening, often doesn't contain much info about why. Or further effects of decisions. Full picture of whole integration involving 20 or 100 systems etc...
Another issue in huge companies spread across the globe is the ability to actually connect with relevant team, and their reluctance to share crucial info. A job security political game is not foreign to devs in some cases. I've had my request for source code of one of our internal security libs, the cornerstone of all of our inter-app authentication, refused with justification that its safer for the company to not share it even within company. Mind you, the .jar wasn't obfluscated at all so JAD got me to almost-compilable version so that effort wasn't even half-assed.
Man, I could spend whole evening telling stories how documentation can be great. Even incomplete, not completely up-to-date one can save your ass from time to time. And tons of time on top of that.
The point of documentation is to communicate to others how to keep developing a code base - what is does, how it does it etc. What form the documentation takes can be fluid, a full fledged wiki or a single readme.md file can fulfill the same role just as well! Some documentation is better than nothing, so start small and then improve it over time.
The problem is most people don't have this mindset. They expect documentation to be right, and when it isn't, they become frustrated and learn to avoid documentation.
* Can be learned from the code: Function A accepts a C-style pointer to a data array.
* Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doing any memory allocation.
* Cannot be known from the code: Even though the data array is initialized to 0 in the current code, function A should not assume that will always be the case. That data array is intended to be used as persistent storage in a future version.
The first one is kind of pointless to document beyond what doxygen already gives you. The second is useful, but not necessary. The third is absolutely essential, because nothing in the current code can possibly tell you about the future intents for changes in the code.
* Cannot be known from the code: Feature F morphed into feature Q, and the function A doesn't really need that array anymore. Since nobody could tell why it was there in the first place, nobody removed it afterwards.
The next time someone has to make changes to function A, they'll be thankful for a comment or commit message that explains the first point above - as it'll let them complete the picture and realize it's no longer needed, so they don't have to worry whether their change is impacting anything else in the program through (mis)use of that array, but they can instead just go ahead and delete it.
At work, documentation gets written when the boss isn't looking. Corporate culture makes writing documentation taboo. The examples of great documentation I am most familiar with are written for open source projects where managers aren't around to hassle people for writing it. Particularly: mpv, ffmpeg, racket, emacs. In my career I have yet to encounter a commercial software project with documentation at this level.
It was still worth it.
What people can do it help allievate the gaps, but sadly, they're not geeting much help from managers and business people this time 'round either.
Some even mentioned "code as documentation". In the end, they just kept finding justifications for not writing documentation or even proper code comments.
Three months after some solution was written, they couldn't explain the thinking behind it or even all the deep dependencies and magic return values because the person who had written the solution had left the team. Even then they were unwilling to see how documentation would have helped.
This repeated with every freaking team I have ever worked with. The only documentation any of those projects had was the one I created while figuring out the code base.
I observed a fundamental laziness in written communication in many developers and to this day I find it puzzling. I sometimes write down a draft of some solution just by myself, like I would explain it to another developer. More often than not, this helps me in highlighting inconsistencies or errors in my thinking.
But there are many legitimate reasons why one would clarify it as "harder" than programming:
- It requires a different skillset, namely writing.
- It is not uncommon for non-english shops to have a policy of documentation in english. That might be sensible, but complicates the task even further.
- In programming, it suffers from the same problems as math: Natural language is more often than not unsuited to express entirely abstract concepts, at least in concise and easily understandable ways.
- Conversely, natural language often lacks the necessary precision to talk about technical details.
- To alleviate all these problems with language somewhat, you might opt to use diagrams. Which requires yet another skillset.
- It requires time. And quite a lot of it actually. Usually more than you need for the actual programming task. This is why most managers care way less about documentation than they should: They know very well that it detracts time from actual programming tasks.
So sure, people tend to be lazy, but there are certainly good reasons why that happens more often in this area of our work than in others.