The Surprising Power of Documentation(vadimkravcenko.com)
vadimkravcenko.com
The Surprising Power of Documentation
https://vadimkravcenko.com/shorts/proper-documentation/
152 comments
There's another category that's missing from most of the (enterprisey) companies I've worked at; procedures. Think of the result of an event storming session; consider all the steps involved in all layers of your application when a user creates a new session, or wants to do X in your application.
Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a system in place where they pay a fixed amount per month, then they pay or get paid back the difference by the end of a contract year.
It's in the energy company's best interest that the monthly amount they pay is on par. The process to adjust this monthly amount is administrative, but in addition to that there's a huge stack of things to deal with across platforms; website, apps, back-end, support, support user interface, etc etc etc.
All the processes involved in just this aspect of the company need to be documented and drawn out as well, because else it has to be figured out from code or various people that happen to have it in their head. That's where a lot of the meeting culture comes from, because there's no one person in charge of this process, and the ones that know enough don't get together to write it down (and then maintain that documentation).
Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a system in place where they pay a fixed amount per month, then they pay or get paid back the difference by the end of a contract year.
It's in the energy company's best interest that the monthly amount they pay is on par. The process to adjust this monthly amount is administrative, but in addition to that there's a huge stack of things to deal with across platforms; website, apps, back-end, support, support user interface, etc etc etc.
All the processes involved in just this aspect of the company need to be documented and drawn out as well, because else it has to be figured out from code or various people that happen to have it in their head. That's where a lot of the meeting culture comes from, because there's no one person in charge of this process, and the ones that know enough don't get together to write it down (and then maintain that documentation).
I hit an oddly specific realization this weekend while working on an architectural spec: I make better documentation with a color multipen.
The reason why is because it allows a diagram to support more of the cross-cutting concerns by drawing a red arrow or a green arrow through things instead of a blue one.
It's a big moment in my realizations around technical communication. Like, I already knew this stuff mattered, but it's made more concrete when you can look at a diagram and the holistic whole helps you make more sense of things even if the details aren't right yet.
The reason why is because it allows a diagram to support more of the cross-cutting concerns by drawing a red arrow or a green arrow through things instead of a blue one.
It's a big moment in my realizations around technical communication. Like, I already knew this stuff mattered, but it's made more concrete when you can look at a diagram and the holistic whole helps you make more sense of things even if the details aren't right yet.
Reminds me of the four types of documentation that sometimes get listed: tutorials, how-to guides, technical reference and explanation. (Usual caveat of all models are wrong but some are useful.) https://documentation.divio.com/
My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.
My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.
I strongly back the Divio system for documentation, it works great. But you should know that the creator of the system doesn't work at Divio anymore and the newest iteration is now called Diataxis https://diataxis.fr/
the divio style docs concept got further refined by the creator with this - https://diataxis.fr/
mostly the same but some additional information for people who are interested
mostly the same but some additional information for people who are interested
I agree with everything you said, especially tailoring documentation for intended purpose.
Except...
Except...
> User docs are simple.
I should probably elaborate. When saying simple, I meant don't add content that doesn't relate to what the user needs to use the product. There's nothing worse than having to read a several paragraphs of unrelated content just to get to the nugget of info which tells you how to actually use the product.
If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.
If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.
To continue this line of thinking: for documents to be useful in helping a customer solve a problem the documents must answer the question 'why would I want to do X.'
A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product.
Providing accessible conceptual guidance can be very challenging depending on the domain.
A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product.
Providing accessible conceptual guidance can be very challenging depending on the domain.
Agreed on a lot of this, but I'd be cautious about saying that any kind of documentation is "simple". Especially when it comes to technical products - be they internal or external.
Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs.
I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date.
[0]: https://www.doctave.com
Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs.
I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date.
[0]: https://www.doctave.com
> disconnected from the engineering cycle
Great phrase!
To me, there are three places that dev-generated documentation can live:
1. The code
2. The issue tracker
3. The version control system
A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere.
Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed.
The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.
Great phrase!
To me, there are three places that dev-generated documentation can live:
1. The code
2. The issue tracker
3. The version control system
A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere.
Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed.
The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.
> You should write three types of documentation. One for users, one for admins and one about architecture.
I use an airplane analogy (different order than your three above):
1. "Congratulations on purchasing your 747"
2. "This is how you replace the auxiliary power unit"
3. "This is how you survive the engine catching fire"
I use an airplane analogy (different order than your three above):
1. "Congratulations on purchasing your 747"
2. "This is how you replace the auxiliary power unit"
3. "This is how you survive the engine catching fire"
1 is not documenting anything, and both 1 and 3 are meant for pilots? Who are the "users" in this analogy?
On the contrary, 1 would be a "quickstart guide", a "welcome pack", or even just a "The first thing that you need to do to your new washing machine/jet aircraft is take the restraining bolts, used for immobilizing it during transport, off."
"1" is for the airline. What does purchasing the plane, or a fleet of such planes, mean to the company? What will be the benefits, duties, obligations wrt to the airplanes, at a high level?
Edit: word choice
Edit: word choice
It could help to use more specific terminology than "docs".
If I'm properly getting your point, you think there should be user manuals, administration and maintenance procedures, and architecture specifications and/or decision records.
If I'm properly getting your point, you think there should be user manuals, administration and maintenance procedures, and architecture specifications and/or decision records.
Surfing close to Robert Horn's Information Mapping. Which is a useful construct, but it's a dangerous idea to think that content information types just sort of live . . out there, somewhere. Content typing will always be context - dependent, which, well, can boil down to "know your audience". But the content types aren't General Truth, they do need audience to be defined, which is where I disagree with the DITA folks.
[deleted]
This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit.
I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* remove any piece of old documentation in case it was still useful. Imagine working on a codebase where 80% of the code was unused or commented out but no one dared changing it just in case (flashback to 2010 with 4000 lines of style.css).
I'd suggest to take a more holistic approach and treat documentation a lot like testing; for that prototype, probably just write the barebones documentation, for the production-ready new feature go all-in and write detailed documentation, tutorials, etc.
If you do want to go deeper with documentation, then you'll need a dedicated team (like a team of testers) that work exclusively on documentation. At some point it does make sense to hire only for that, and it can even be a differentiating point for your startup if done correctly.
For libraries, a ratio I've seen works pretty well is approx 1:3:5 for lines of code:tests:docs; you can do tests first, or even documentation first, but once everything is finished and if you count the amount of lines that's a decent ratio. Note that when counting "lines of docs" in an editor, a whole paragraph will count as just 1, so in reality there's a lot more docs.
Note: I'm the creator of both https://documentation.page/ and https://documentation.agency/
* (only 2 "negative" paragraphs on a book-length article)
I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps* remove any piece of old documentation in case it was still useful. Imagine working on a codebase where 80% of the code was unused or commented out but no one dared changing it just in case (flashback to 2010 with 4000 lines of style.css).
I'd suggest to take a more holistic approach and treat documentation a lot like testing; for that prototype, probably just write the barebones documentation, for the production-ready new feature go all-in and write detailed documentation, tutorials, etc.
If you do want to go deeper with documentation, then you'll need a dedicated team (like a team of testers) that work exclusively on documentation. At some point it does make sense to hire only for that, and it can even be a differentiating point for your startup if done correctly.
For libraries, a ratio I've seen works pretty well is approx 1:3:5 for lines of code:tests:docs; you can do tests first, or even documentation first, but once everything is finished and if you count the amount of lines that's a decent ratio. Note that when counting "lines of docs" in an editor, a whole paragraph will count as just 1, so in reality there's a lot more docs.
Note: I'm the creator of both https://documentation.page/ and https://documentation.agency/
* (only 2 "negative" paragraphs on a book-length article)
I'm the CTO of Mintlify - we help other startups create their developer-facing documentation. We've been working in the documentation space for a little over a year now and I spend a lot of time thinking about documentation. I completely agree here.
Documentation is such a hard problem to "solve" if you're a fast-moving startup. You need a mixture of creating a documentation-first culture and acknowledging that documentation is difficult to maintain. Ultimately you end up creating processes to help people document their intent, decisions and the mission critical information.
There is also such a large range of types of documentation - varying scale from internal to external and technical to non-technical.
We started by creating https://writer.mintlify.com/ which really resonated with developers because it made it easier to write documentation, but it only helped generate documentation that was highly technical and close to the code. We decided to stay in the documentation space but try another vector and so now we're taking a crack at public-facing documentation - which in my opinion is a different can of worms than internal documentation. However as I'm building and growing my startup and I find myself continuously playing whack-a-mole and I definitely hope that we can build the foundation and expand to make it easier to maintain all different types of documentation.
Documentation is such a hard problem to "solve" if you're a fast-moving startup. You need a mixture of creating a documentation-first culture and acknowledging that documentation is difficult to maintain. Ultimately you end up creating processes to help people document their intent, decisions and the mission critical information.
There is also such a large range of types of documentation - varying scale from internal to external and technical to non-technical.
We started by creating https://writer.mintlify.com/ which really resonated with developers because it made it easier to write documentation, but it only helped generate documentation that was highly technical and close to the code. We decided to stay in the documentation space but try another vector and so now we're taking a crack at public-facing documentation - which in my opinion is a different can of worms than internal documentation. However as I'm building and growing my startup and I find myself continuously playing whack-a-mole and I definitely hope that we can build the foundation and expand to make it easier to maintain all different types of documentation.
I'm trying your extension out and it looks promising.
A tiny bit of feedback: the shortcut key is defined in settings, not keybindings which seems wrong? Also, the default is to override cmd+. which is an important shortcut already..
A tiny bit of feedback: the shortcut key is defined in settings, not keybindings which seems wrong? Also, the default is to override cmd+. which is an important shortcut already..
I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically.
Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice.
In my eyes one of the biggest problems with keeping documentation up to date is that over time the mapping between the piece of code you are documenting and the place where you find it in the documentation becomes more complex, to a point where missing something is not unlikely. Rust's documentation-in-code-approach addresses this problem neatly.
Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice.
In my eyes one of the biggest problems with keeping documentation up to date is that over time the mapping between the piece of code you are documenting and the place where you find it in the documentation becomes more complex, to a point where missing something is not unlikely. Rust's documentation-in-code-approach addresses this problem neatly.
I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_height method "gets the height", and that its return value is the height. A more high level problem with this is that you get documentation that is just as fragmented as the code and where the high level usage of things is not explained at all. Also it clutters the code with many highly trivial remarks.
I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code.
get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it change any of its parameters? Who deallocates the return value? Do you need to hold a lock somwhere?
Of course it might be a good idea to group together get_height, get_width, get_diagonal and get_depth if the above is all the same for those. But having no documentation just because you think it is trivial that get_height gets some height from somewhere just means that you are sloppy and didn't think of all of the above. So your code shouldn't be touched with a 10-foot-pole imho.
My solution, which I personally hate but know of no alternative to, is a documentation template for each function asking the above questions (depending on runtime and language of course) that I give people to fill in. Until they learn...
get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it change any of its parameters? Who deallocates the return value? Do you need to hold a lock somwhere?
Of course it might be a good idea to group together get_height, get_width, get_diagonal and get_depth if the above is all the same for those. But having no documentation just because you think it is trivial that get_height gets some height from somewhere just means that you are sloppy and didn't think of all of the above. So your code shouldn't be touched with a 10-foot-pole imho.
My solution, which I personally hate but know of no alternative to, is a documentation template for each function asking the above questions (depending on runtime and language of course) that I give people to fill in. Until they learn...
Most of what you described as needing documentation could be expressed as code (mixing multiple languages here to express the point more clearly)
const fn get_outer_height() -> Result<SomeErrorType, WeakReference<Number>>
- `const` makes it clear this doesn't mutate
- the function name says exactly what it does
- The return type makes it clear it can return an error
- The return value is typed in a way that makes it clear what the ownership is
Throw in a language like Rust that gives guarantees about thread safety and now the only thing left is if the API is stable or not. Which I would argue doesn't matter much at all since people will still end up depending on it regardless of the comment saying "This API might not be stable"
And the best part? My definition will never get outdated. If the assumptions change, the definition will also need to change (well, except for maybe the name)
const fn get_outer_height() -> Result<SomeErrorType, WeakReference<Number>>
- `const` makes it clear this doesn't mutate
- the function name says exactly what it does
- The return type makes it clear it can return an error
- The return value is typed in a way that makes it clear what the ownership is
Throw in a language like Rust that gives guarantees about thread safety and now the only thing left is if the API is stable or not. Which I would argue doesn't matter much at all since people will still end up depending on it regardless of the comment saying "This API might not be stable"
And the best part? My definition will never get outdated. If the assumptions change, the definition will also need to change (well, except for maybe the name)
You are absolutely right, and one should prefer languages that can give such guarantees wherever possible.
But often one doesn't have a choice. People still write software in inferior languages such as Javascript or Python, where you cannot even be sure about a return or parameter data type.
But often one doesn't have a choice. People still write software in inferior languages such as Javascript or Python, where you cannot even be sure about a return or parameter data type.
To add to what you're saying:
Quite often something is not obvious or trivial to someone who is examining a piece of code or using a library for the first time because it assumes the person already understands the context.
An example of what I mean: perhaps it is because I have a background in the sciences, but I assume that most properties have units. A property such as height certainly does have units. So is get_height() returning the height in pixels, inches, meters, or something else? I have also been bitten by graphics libraries that measure distances in unexpected (to me) way. Is the radius of the arc with line thickness 'n' using the inside radius, outside radius, center line, or something else? The person writing the original code may think the developer using their code down the road can test different assumptions, yet the reality is the number of combinations to test will rarely be trivial (and that is assuming they identify the correct parameters to test).
It's at the point where I refuse to even consider using libraries that leave out documentation for obvious things. Even comments like "gets the height" raises red flags since it is a demonstration that the author did not put any thought into what they are documenting.
Quite often something is not obvious or trivial to someone who is examining a piece of code or using a library for the first time because it assumes the person already understands the context.
An example of what I mean: perhaps it is because I have a background in the sciences, but I assume that most properties have units. A property such as height certainly does have units. So is get_height() returning the height in pixels, inches, meters, or something else? I have also been bitten by graphics libraries that measure distances in unexpected (to me) way. Is the radius of the arc with line thickness 'n' using the inside radius, outside radius, center line, or something else? The person writing the original code may think the developer using their code down the road can test different assumptions, yet the reality is the number of combinations to test will rarely be trivial (and that is assuming they identify the correct parameters to test).
It's at the point where I refuse to even consider using libraries that leave out documentation for obvious things. Even comments like "gets the height" raises red flags since it is a demonstration that the author did not put any thought into what they are documenting.
I don't agree with this answer. I fully agree that documentation is important, needs to be correct and maintained. However, I do stand by the original poster saying that it is often a bad idea to enfroce javadoc style comments to autogenerate documentation. This often leads to low quality documentation.
Like you say, get_height is a trivial function, but still requires attention. Enforcing in-code docs is not going to help to have higher quality docs, quite the contrary. You often get low effort stuff, just to make the code checker happy.
And if you put in a peer review process to validate the in-code comment, it loses all power because you might as well use that step for decent documentation. get_height should be documented in a logical place, where it makes sense indeed, like grouped with get_width. But now you have the logical place to put your documentation, and the forced javadoc comment. That's double work, and one of them will be bad quality as a result of it.
Nobody is arguing for no documentation, but I am arguing for avoiding javadoc enforcements. My solution is much simpler: have a documentation check as part of the peer review process. Sure, have a template for the documentation, but don't make it strict. Ours is simple: all juniors are on documentation peer review as part of their onboarding. If they don't get it, it needs to be fixed.
Our peer review process is quite simple: is the documentation adapted, is there a relevant unit test (we actually have low UT coverage, we only do them for critical code and as part of bug fixing, so enforced frameworks make no sense for us), and naturally is the code quality itself ok
But many companies don't do those, yeah well thats how you get shit.
Like you say, get_height is a trivial function, but still requires attention. Enforcing in-code docs is not going to help to have higher quality docs, quite the contrary. You often get low effort stuff, just to make the code checker happy.
And if you put in a peer review process to validate the in-code comment, it loses all power because you might as well use that step for decent documentation. get_height should be documented in a logical place, where it makes sense indeed, like grouped with get_width. But now you have the logical place to put your documentation, and the forced javadoc comment. That's double work, and one of them will be bad quality as a result of it.
Nobody is arguing for no documentation, but I am arguing for avoiding javadoc enforcements. My solution is much simpler: have a documentation check as part of the peer review process. Sure, have a template for the documentation, but don't make it strict. Ours is simple: all juniors are on documentation peer review as part of their onboarding. If they don't get it, it needs to be fixed.
Our peer review process is quite simple: is the documentation adapted, is there a relevant unit test (we actually have low UT coverage, we only do them for critical code and as part of bug fixing, so enforced frameworks make no sense for us), and naturally is the code quality itself ok
But many companies don't do those, yeah well thats how you get shit.
> get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects?
In my experience, if your documentation covers all these aspects it's guaranteed to be either wrong, misleading, or out of date on any of these details, and you better read the actual code to be sure.
In particular, the answer will often be "it depends on what the rest of the system does". Perhaps it delegates the actual calculation to an API, and this doc won't change when the API changes in a _mostly_ compatible way.
I mean, even with the best efforts given, code has bugs, words are vague, there's no way you should trust the dev who wrote the code to properly convey what it actually does.
In my experience, if your documentation covers all these aspects it's guaranteed to be either wrong, misleading, or out of date on any of these details, and you better read the actual code to be sure.
In particular, the answer will often be "it depends on what the rest of the system does". Perhaps it delegates the actual calculation to an API, and this doc won't change when the API changes in a _mostly_ compatible way.
I mean, even with the best efforts given, code has bugs, words are vague, there's no way you should trust the dev who wrote the code to properly convey what it actually does.
Wouldn't it be more efficient to just read the source code? Also, the point the guy you're responding to is making is not that code shouldn't be documented, but that in-line documentation of this variety is not that great. You seem to be interpreting him to be saying that the code shouldn't be documented at all, which is not what he is saying.
It's true that there can be gotcha's in code which should be documented, but I don't think forcing a template on people is the solution. In fact, I wouldn't expect people to be better at documenting them with that in place.
Well, yes, you need to have manual or automatic checks for the presence of the template, and the correctness of the contents is often uncheckable by automated tests. But if things break and e.g. the filled-in documentation template incorrectly said "thread-safe: yes", it will be very easy to 'git blame' the culprit. That way you can at least slowly weed out the sloppy documenters, but I admit that this is tedious.
And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.
And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.
Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I reread the program and make the necessary changes.
Literate programming is great until your code base becomes unwieldy. Then you need a README.md file which acts like a pointer to the correct entry points.
Then as the code grows, you need to document the architecture, add small gotchas, etc.
At the end of the day, documentation wins.
Then as the code grows, you need to document the architecture, add small gotchas, etc.
At the end of the day, documentation wins.
I am very code literate, but depending on the size of the codebase and how much smoke and mirrors are used, I might take longer to grok how things are interconnected by reading the code than it would take me if someone gave an high level overview in a paragraph or two.
I understand the sentiment, because I hate this in other languages too. But somehow in Rust it works. Of course there is also bad documentation of the kind you describe, but that is a different problem.
Bridging the gap between a prosaic high level explaination (how do the parts work together?) and a fine grained explaination of each part (what does that part do?) can be a challenge. Rust solves this somewhat by allowing you to do module level documentation (that can essentially look like a blog post, only that the examples get checked when the code is tested) and it lets you link to different entites.
I would always prefer a well written blog post, if people were able to keep the examples working and the code up to date. But experience shows they are not.
I'd rather have generated documentation that is true than a blog post where half of the examples won't work, because nobody bothered to update the post after the code changed. The first might at times be barren if done badly, the latter is downright misleading.
Bridging the gap between a prosaic high level explaination (how do the parts work together?) and a fine grained explaination of each part (what does that part do?) can be a challenge. Rust solves this somewhat by allowing you to do module level documentation (that can essentially look like a blog post, only that the examples get checked when the code is tested) and it lets you link to different entites.
I would always prefer a well written blog post, if people were able to keep the examples working and the code up to date. But experience shows they are not.
I'd rather have generated documentation that is true than a blog post where half of the examples won't work, because nobody bothered to update the post after the code changed. The first might at times be barren if done badly, the latter is downright misleading.
I am firmly on the opinion that every bit of public interface should get a documentation string.
You say "gets the height" is trivial, but that text tells not only what the function does, but also that the author couldn't think of anything else important to say. This is very different from no text at all, where you can't be certain if the author even thought about it.
IMO, enforcing an internal structure (AKA "you must document each parameter and the return value") is counter-productive, but enforcing the existence of the comment is very productive.
> Also it clutters the code with many highly trivial remarks.
I'd say that it "clutters" the code with markers for public elements and hard to understand ones. Those are actually valuable, and not clutter at all.
Anyway, if those markers are a large share of your lines, you may need to rethink your architecture. It's usually not valuable to have a lot of interface for trivial things.
You say "gets the height" is trivial, but that text tells not only what the function does, but also that the author couldn't think of anything else important to say. This is very different from no text at all, where you can't be certain if the author even thought about it.
IMO, enforcing an internal structure (AKA "you must document each parameter and the return value") is counter-productive, but enforcing the existence of the comment is very productive.
> Also it clutters the code with many highly trivial remarks.
I'd say that it "clutters" the code with markers for public elements and hard to understand ones. Those are actually valuable, and not clutter at all.
Anyway, if those markers are a large share of your lines, you may need to rethink your architecture. It's usually not valuable to have a lot of interface for trivial things.
You've put your finger on exactly why I don't like this kind of documentation.
Also, I don't tend to trust it as much, because it isn't actually what the program executes.
When I'm trying to read the source code I don't want to read about the source code -- I want to read the actual source code -- and if I keep coming across long multi-line idiotic comments then it breaks my flow and concentration.
I like the source code itself to be extraordinarily readable, with long and descriptive variable and method names, but I want it to be dense and packed into paragraphs of sense.
To the extent there are any comments at all they should be extremely short and completely clarifying -- they should not even partially overlap with information conveyed through function or variable names, for instance.
Also, I don't tend to trust it as much, because it isn't actually what the program executes.
When I'm trying to read the source code I don't want to read about the source code -- I want to read the actual source code -- and if I keep coming across long multi-line idiotic comments then it breaks my flow and concentration.
I like the source code itself to be extraordinarily readable, with long and descriptive variable and method names, but I want it to be dense and packed into paragraphs of sense.
To the extent there are any comments at all they should be extremely short and completely clarifying -- they should not even partially overlap with information conveyed through function or variable names, for instance.
> Also, I don't tend to trust it as much, because it isn't actually what the program executes.
Maybe you don't know Rust, but it is a strongly typed language. If you go to a rust project and run `cargo doc --open` you will see exactly what the type system lays out. Sure if someone writes "changes the windows height and returns a new Window" on a change_window_height(height: Pixels) -> Window and it changes the windows width instead that is still wrong. But (A) you can click on "source" and see the actual code and (B) you are guaranteed that the function takes Pixels and spits out a Window
That being said I hate that kind of documentation in most other languages, not in Rust. In Rust it is basically an alternative view onto the same code with a (needed) emphasis on the realtions of the entities the type system describes. If there is prose that can be a nice extra, but cargo doc is even useful without a single comment.
Maybe you don't know Rust, but it is a strongly typed language. If you go to a rust project and run `cargo doc --open` you will see exactly what the type system lays out. Sure if someone writes "changes the windows height and returns a new Window" on a change_window_height(height: Pixels) -> Window and it changes the windows width instead that is still wrong. But (A) you can click on "source" and see the actual code and (B) you are guaranteed that the function takes Pixels and spits out a Window
That being said I hate that kind of documentation in most other languages, not in Rust. In Rust it is basically an alternative view onto the same code with a (needed) emphasis on the realtions of the entities the type system describes. If there is prose that can be a nice extra, but cargo doc is even useful without a single comment.
This is API reference documentation. What you're missing is conceptual documentation and use case examples.
Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect.
Use case examples string together multiple APIs, multiple domain objects, to achieve a high level business objective. When working on a project, you can sometimes get away without this - the existing code can be example enough to copy. You can end up with cargo culting, people copying things without understanding why. But if you have an API for third-party use, which needs documenting, you need to have either a well-seeded set of open source users, or a great set of examples.
Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect.
Use case examples string together multiple APIs, multiple domain objects, to achieve a high level business objective. When working on a project, you can sometimes get away without this - the existing code can be example enough to copy. You can end up with cargo culting, people copying things without understanding why. But if you have an API for third-party use, which needs documenting, you need to have either a well-seeded set of open source users, or a great set of examples.
Rustdoc supports conceptual documentation quite well, including testing the example code. A specialized page is better, but the pareto principle applies.
See the Clap documentation:
https://docs.rs/clap/latest/clap/
See the Clap documentation:
https://docs.rs/clap/latest/clap/
I often call this narrative documentation. It's the antidote to Chesterton's Fence and explains the thinking of the programmer who created the thing. How did that programmer expect people to use their tool.
Most popular languages have a version of this, including Java. This is only one level of documentation, and one must know a bit about what they don't know to use it effectively. In other words, if you already know that you need to use the foo function, then the foo function's documentation is great. If you don't even know which function or class/module to use, it isn't a great starting point.
I built a testing library on top of pytest based upon the idea of doing this mapping at an application level instead of a method/function/class level.
If you write tests in a strongly typed, non-turing complete markup (in this case, StrictYAML), you can then use it with a template and test artefacts (e.g. app screenshots) to generate readable how-to/tutorial docs which are guaranteed to stay up to date.
https://github.com/hitchdev/hitchstory
This isn't a new idea, but I find that people are often skeptical because there's a history of people getting their fingers burned by Gherkin's language design or YAML's weak typing (both of which are completely valid).
If you write tests in a strongly typed, non-turing complete markup (in this case, StrictYAML), you can then use it with a template and test artefacts (e.g. app screenshots) to generate readable how-to/tutorial docs which are guaranteed to stay up to date.
https://github.com/hitchdev/hitchstory
This isn't a new idea, but I find that people are often skeptical because there's a history of people getting their fingers burned by Gherkin's language design or YAML's weak typing (both of which are completely valid).
>I've worked in multiple* companies where the problem was too much documentation, and of course everyone was afraid to update or ghasps*
That must be nice. I've yet to work on a company where half my time wasn't trying to prod for some resource (be it internal code, a public 3rd party tool, or even the resource itself), sometimes playing a game of goose just to figure out who knows the author. I'd love too much documentation.
But I understand your point. The only thing worse than no documentation is wrong documentation, and outdated docs half the time can become outright wrong half the time, if it isn't simply encouraging outdated but functional practices. Tech writers are highly undervalued for that purpose.
I should also mention that the ability to properly search for docs is almost more important than the doc itself. Some companies had wikis but good luck searching for the right keywords if you didn't know the exact title. A properly categorized top level page could have helped a lot (and is probably easier/cheaper than integrating google like searchabilty into an internal database).
That must be nice. I've yet to work on a company where half my time wasn't trying to prod for some resource (be it internal code, a public 3rd party tool, or even the resource itself), sometimes playing a game of goose just to figure out who knows the author. I'd love too much documentation.
But I understand your point. The only thing worse than no documentation is wrong documentation, and outdated docs half the time can become outright wrong half the time, if it isn't simply encouraging outdated but functional practices. Tech writers are highly undervalued for that purpose.
I should also mention that the ability to properly search for docs is almost more important than the doc itself. Some companies had wikis but good luck searching for the right keywords if you didn't know the exact title. A properly categorized top level page could have helped a lot (and is probably easier/cheaper than integrating google like searchabilty into an internal database).
> That must be nice
> The only thing worse than no documentation is wrong documentation
Yeah, that was the exact problem. One was a startup and when I joined it was all mostly up-to-date so it was great! But by the time I left (after 2 major migrations) most of it was out of date and a nightmare to find anything updated, any script that could still be run, etc.
> The only thing worse than no documentation is wrong documentation
Yeah, that was the exact problem. One was a startup and when I joined it was all mostly up-to-date so it was great! But by the time I left (after 2 major migrations) most of it was out of date and a nightmare to find anything updated, any script that could still be run, etc.
> Imagine working on a codebase where 80% of the code was unused or commented out
That's not documentation; that's code.
That's not documentation; that's code.
>> That's not documentation; that's code.
It's an analogy to make the point - we delete old code that's not relevant any more. Imagine reading documentation where 80 percent of it is no longer relevant but is kept around "just in case".
It's an analogy to make the point - we delete old code that's not relevant any more. Imagine reading documentation where 80 percent of it is no longer relevant but is kept around "just in case".
[deleted]
It's hard to argue with, especially if you've experienced using good documentation. OpenBSD's man pages are one example. It takes a little time to break the habit of checking Google first and instead checking the man page first (you eventually learn that you rarely need more than that).
The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things change. As the author notes, it will have to be something that is made part of the culture of the organization. And given that recent agile programming approaches proclaim that "the code is the documentation" and that formal, separate documentation is an impediment to productivity, you'll find that many developers will dig in their heels if asked to write documentation.
Bad, outdated, or just plain wrong documentation can be worse than nothing, as it tends to lead you to incorrect conclusions and beliefs about the system.
The key word is "good" documentation. That takes time and effort to write, and it takes time and effort to keep it updated as things change. As the author notes, it will have to be something that is made part of the culture of the organization. And given that recent agile programming approaches proclaim that "the code is the documentation" and that formal, separate documentation is an impediment to productivity, you'll find that many developers will dig in their heels if asked to write documentation.
Bad, outdated, or just plain wrong documentation can be worse than nothing, as it tends to lead you to incorrect conclusions and beliefs about the system.
> OpenBSD's man pages are one example.
OpenBDS's developer to user ratio must be less that 1 to 1000s. When you update one line of document, you're probably saving time for thousands of users accross years of use.
Most project I worked on had at most a few dozen people with an actual chance of reading the documentation, and the majority of them aren't users, they'll be reading all the code anyway because they're not in a position to blindly trust the documentaton.
Why should we calculate the ROI of the time spend on maintaining good documentation the same way in both cases ?
PS: I also think a distinction should be made between specification and documentation. It feels that both are conflated too many times.
OpenBDS's developer to user ratio must be less that 1 to 1000s. When you update one line of document, you're probably saving time for thousands of users accross years of use.
Most project I worked on had at most a few dozen people with an actual chance of reading the documentation, and the majority of them aren't users, they'll be reading all the code anyway because they're not in a position to blindly trust the documentaton.
Why should we calculate the ROI of the time spend on maintaining good documentation the same way in both cases ?
PS: I also think a distinction should be made between specification and documentation. It feels that both are conflated too many times.
ROI should always be a consideration. It's reasonable to argue the merits of documentation. It may even be reasonable to argue that most projects would benefit from increased documentation. Without knowing how long it will take to write it and how many people will use it, you cannot reasonably insist that writing more documentation should be a priority for every project.
Much like automation, the question should be phrased in terms of how long it will take and how much time it will save. https://xkcd.com/1205/
Much like automation, the question should be phrased in terms of how long it will take and how much time it will save. https://xkcd.com/1205/
All of the above. But as someone who writes documentation let me add, most programmers are bad writers.
To write good documentation you need to mix technical reference (the easy part) with user reference. The latter requires you to imagine where the user is at, and take them to where they understand. This is hard to do, and requires well, skills.
So a culture of documentation is great, but quality matters as much as quantity. Clarity, completeness and coherence are all legs of the stool.
To write good documentation you need to mix technical reference (the easy part) with user reference. The latter requires you to imagine where the user is at, and take them to where they understand. This is hard to do, and requires well, skills.
So a culture of documentation is great, but quality matters as much as quantity. Clarity, completeness and coherence are all legs of the stool.
Certainly writing is a skill that many programmers are not good at.
However IMO an easy trap to fall into is to start documenting without a bigger understanding of the audience and the purpose of the doc.
A good way to start is to identify which of the 4 types of documentation you are working on.
https://nick.groenen.me/posts/the-4-types-of-technical-docum...
Personally I find it very easy to put too much explanation in the wrong places.
However IMO an easy trap to fall into is to start documenting without a bigger understanding of the audience and the purpose of the doc.
A good way to start is to identify which of the 4 types of documentation you are working on.
https://nick.groenen.me/posts/the-4-types-of-technical-docum...
Personally I find it very easy to put too much explanation in the wrong places.
This issue around poor writing skills is something that I've thought/worried about for a while. At some level of seniority (the more junior the better IMO) we expect developers to write design docs. The inability to communicate clearly in those documents is a huge problem. Oftentimes misunderstandings and ambiguities are cleared up at design review, but then never reintegrated into the document, leaving two artifacts, the implementation and the design doc. These obviously drift over time, maintaining correspondence is hard. But when one only ambiguously described the other from the get go, then the documentation is broken. This too is technical debt.
If you are fortunate, you can write code in an organization which has a high code quality bar, uses consistent styles etc. But it is rare (vanishingly so I nearly 30 years experience) to find the same bar applied to the design docs.
If you are fortunate, you can write code in an organization which has a high code quality bar, uses consistent styles etc. But it is rare (vanishingly so I nearly 30 years experience) to find the same bar applied to the design docs.
You also need technical writers.
Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".
another key word is "searchable" documentation, and that's where man pages fail big time leading you to the likes of Google
What degree of „searchable“ are you missing from apropos?
https://man.openbsd.org/apropos.1
https://man.openbsd.org/apropos.1
All of the basics of anything google-like: typo-friendliness with word forms and phrases, links to source, formatting of output, GUI, or not spamming the output with a dozen of lines of warnings that some man page files are missing.
Then a bunch more degrees that I could know about if the tool were more usable
Then a bunch more degrees that I could know about if the tool were more usable
Yes.
I mostly use man pages when I already basically know the program and need to do specific thing.
Even then I don't use man itself but usually a webpage of the manfile because of UX.
I mostly use man pages when I already basically know the program and need to do specific thing.
Even then I don't use man itself but usually a webpage of the manfile because of UX.
I'll add that what a lot of non-developers seem to think is documentation is not actually worth very much. For instance, a 2 hour recording of a zoom meeting tagged only with a date and general topic is worth so much less than a searchable text guide on the same topic. Recording a meeting is not documentation! Especially if it's not tagged properly and made available to the people who need it. It's also impossible to update a meeting recording of course so it's guaranteed to be out of date after enough time passes, requiring that meeting to be held and recorded again.
Other things that I see treated as documentation when they're not: slack messages, uncommented code ("self-documenting" code exists, but it's much rarer than management seems to insist), vague jira tickets, some guy who worked on the app 5 years ago and is happy to answer questions even though he's in a new role now, etc.
Other things that I see treated as documentation when they're not: slack messages, uncommented code ("self-documenting" code exists, but it's much rarer than management seems to insist), vague jira tickets, some guy who worked on the app 5 years ago and is happy to answer questions even though he's in a new role now, etc.
This is one thing that has always bothered me! A lot of clients ask if I have checked the documentation when I have a very specific question. The documentation however, is just a drive of a bunch of recorded meetings with no tags or transcripts. Am I really supposed to linearly look through tens of hours of recorded meetings to see of the detail might have been mentioned on one of those?
If they are clients or people responsible for any kind of budget, just phrase it as a business offer: I can watch through the 89 hours of relevant documentation in 89 hours for $165 an hour. Pricing fixed if accepted within 2 weeks of offering date.
Well, we have Whisper now, so you can transcribe them and search.
I have found that the post meeting notes written by at least two persons then consolidated and improved by others really do help. Recordings while better than nothing would have to have transcripts in order to be usable. Hard to watch hour long recording searching for the relevant 5mins.
One of the surprising difficulties of creating a good culture around documentation I found is getting people to actually read and use it. I guess the root cause of this is bad documentation itself, so developers come to not expect to find anything useful in there and just ignore it by default.
I've often seen developers who spend hours fiddling on some detail that was clearly mentioned in the readme of the very same repository containing the code on which they are stuck, or who just failed to read the extensive documentation and proceed to 1) run the code and 2) call me for help. Furthermore, I've actually caught myself doing the same more than once.
This led me to think that for a good documentation culture, the primary question should be: how are developers actually going to use and benefit from the docs? How documentation will get updated is the second question of importance, and writing documentation comes third.
I've often seen developers who spend hours fiddling on some detail that was clearly mentioned in the readme of the very same repository containing the code on which they are stuck, or who just failed to read the extensive documentation and proceed to 1) run the code and 2) call me for help. Furthermore, I've actually caught myself doing the same more than once.
This led me to think that for a good documentation culture, the primary question should be: how are developers actually going to use and benefit from the docs? How documentation will get updated is the second question of importance, and writing documentation comes third.
I admit, I rarely read documentation of anything, since I have no clue whether to trust it, so I will usually try to just follow my logical thought process of figuring out the solution or by trial and error.
This also makes me bad myself at documentation, because if I don't use it I also feel internally that no one would read what I write in the first place also.
Out of responsibility I will try to document shared things, but I never feel productive while doing that, I feel like I am just writing into a void.
This also makes me bad myself at documentation, because if I don't use it I also feel internally that no one would read what I write in the first place also.
Out of responsibility I will try to document shared things, but I never feel productive while doing that, I feel like I am just writing into a void.
> I rarely read documentation of anything, since I have no clue whether to trust it
There's another big issue with documentation; it's often a write-and-forget thing. I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
There's another big issue with documentation; it's often a write-and-forget thing. I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
That happens when you have legal requirement on the documentation. The same way you have an accountant peering over and keeping track of every transaction that happens in your company.
Short of that you'll need to explain why the company is losing money because Jim didn't write a full explanation on why his "getUserIdOrNull" function returns null when the user id is not available.
Short of that you'll need to explain why the company is losing money because Jim didn't write a full explanation on why his "getUserIdOrNull" function returns null when the user id is not available.
> I'm confident every team or department should have a full-time documentation owner whose job it is to ensure documentation is up to date, maintained, and verified.
I'm not convinced this would work. Such a person wouldn't have time to be a subject matter expert at anything other than the documentation tools. They wouldn't understand what they were writing about.
I'm not convinced this would work. Such a person wouldn't have time to be a subject matter expert at anything other than the documentation tools. They wouldn't understand what they were writing about.
I think one of the most important features for documentation is that it needs to earn people's trust.
If people expect that the docs won't be comprehensive or will be out-of-date, they won't use them.
This is why I'm so keen on documentation living in the same repo as the rest of the project. That way it can be kept up-to-date with the state of the code, through a policy where PRs are only merged when they include the relevant documentation updates.
Having that policy in place really helps people learn to both write and read the documentation.
If people expect that the docs won't be comprehensive or will be out-of-date, they won't use them.
This is why I'm so keen on documentation living in the same repo as the rest of the project. That way it can be kept up-to-date with the state of the code, through a policy where PRs are only merged when they include the relevant documentation updates.
Having that policy in place really helps people learn to both write and read the documentation.
Exactly. Good documentation is much harder than you'd think.
I had similar policies. Also periodic reviews and especially during onboarding new devs I had them review the docs and make a list of missing points etc
Its just as important to delete out of date topics. Wrong and stale info is costly, it decreases trust and sends people in wrong directions.
edit: another obvious but surprisingly difficult thing to do is have everything in one system and make sure everything knows where to find it. Especially if your org is a bit bigger everybody will have their own systems and it'll be a big mess before you know it. But even so, within a single project I've often seen 3 to 8 'sources of truth', like trello tickets, images in onedrive, a word doc, markdown files, various propietary formats, pinnend posts in chat system, email archives, etc, etc.
I had similar policies. Also periodic reviews and especially during onboarding new devs I had them review the docs and make a list of missing points etc
Its just as important to delete out of date topics. Wrong and stale info is costly, it decreases trust and sends people in wrong directions.
edit: another obvious but surprisingly difficult thing to do is have everything in one system and make sure everything knows where to find it. Especially if your org is a bit bigger everybody will have their own systems and it'll be a big mess before you know it. But even so, within a single project I've often seen 3 to 8 'sources of truth', like trello tickets, images in onedrive, a word doc, markdown files, various propietary formats, pinnend posts in chat system, email archives, etc, etc.
I've done that and still do.
It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before.
Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome".
Fundamentally there's a lack of shame about not reading things. It's not unique to the software world either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by things they claim they read that morning, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really.
It's possible AI can help here. Some people just don't want to sit down and read, but they'll ask questions, so an AI that reads the docs regularly could motivate people to write it. Or you could use them for code review enforcement by giving them changes and asking, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.
It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before.
Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome".
Fundamentally there's a lack of shame about not reading things. It's not unique to the software world either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by things they claim they read that morning, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really.
It's possible AI can help here. Some people just don't want to sit down and read, but they'll ask questions, so an AI that reads the docs regularly could motivate people to write it. Or you could use them for code review enforcement by giving them changes and asking, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.
I've done that and still do.
It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before.
Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome".
Fundamentally there's a lack of shame about not reading things. It's not unique to software either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by docs they claim they've read, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really.
One fix I'm experimenting with at the moment is for a Linux kernel style hierarchy of reviewers where everyone gets their own repo and they merge upwards, so there's at least clear ownership and if someone is consistently letting docs rot that becomes apparent to the ultimate TL when they do a quick eyeball of big merges.
It may also be worth experimenting with large language models. They could be given a change and asked, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.
It helps a bit, but only if your code reviewers are actually going to enforce the rule. It seems like most programmers simply don't like reading or writing documentation even though they can save large amounts of time for everyone by doing so. Certainly it's frustrating to be told e.g. "this thing we use can't do X" when how to do X is discussed in the thing's user guide, simply because someone didn't want to read it. I've had that experience before.
Code reviews let you force the issue for a while but it's hard to scale. Getting other people to enforce the same rules via review is difficult. Many devs will be really strict about things like unit testing and make it a point of pride, but not at all strict at all about updating docs. Other devs will learn which reviewers let them avoid writing things in English and send reviews there preferentially, or find other ways to dodge it. Fixing this via training or policy turned out to be nigh-on impossible: many people simply will not change regardless of how many times you send a code review back for missing docs. Nor will they change even when their questions are constantly being answered by a link to the docs, which they don't take as "you should be embarrassed that I had to google that for you" but rather "hey here's a helpful link, you're welcome".
Fundamentally there's a lack of shame about not reading things. It's not unique to software either. People ask questions answered by docs, or even by emails they just received, or they make bold assertions contradicted by docs they claim they've read, and when this is pointed out they just shrug it off in a way they wouldn't do if an obvious bug snuck through that should have been caught by testing. It's a cultural issue and needs to change, really.
One fix I'm experimenting with at the moment is for a Linux kernel style hierarchy of reviewers where everyone gets their own repo and they merge upwards, so there's at least clear ownership and if someone is consistently letting docs rot that becomes apparent to the ultimate TL when they do a quick eyeball of big merges.
It may also be worth experimenting with large language models. They could be given a change and asked, "given policy X, should this change have updated the documentation?" and if the LLM says yes then that gets flagged centrally for followup, for example.
Unfortunately, most cultures teach developers not to read. Between having barely any documentation, poor discoverability of said documentation, poor quality documentation, teaching people to 'talk at the first sign of trouble', it is only natural this is the outcome.
Now we're stuck with both a chicken-and-egg problem at most places, while in places with decent documentation, many developers still come in not reading it, discouraging any significant upkeep of existing documentation.
Now we're stuck with both a chicken-and-egg problem at most places, while in places with decent documentation, many developers still come in not reading it, discouraging any significant upkeep of existing documentation.
In my experience, not everybody is good at writing good documentation.
I usually see software build by brilliant engineers, people much smarter than I at building software, and the documentation sucks.
Not that is not there, but that is very difficult to understand.
It is clear to me that you can be very smart at doing certain things (for example writing software) and suck at others (writing documentation).
I usually see software build by brilliant engineers, people much smarter than I at building software, and the documentation sucks.
Not that is not there, but that is very difficult to understand.
It is clear to me that you can be very smart at doing certain things (for example writing software) and suck at others (writing documentation).
I never start with documentation, but I find it immensely useful. Usually it starts with someone asking about something and you can just link them to the docs without having to talk to them.
You’re indirectly pointing to two ongoing problems with docs: discoverability and findability. Can you accidentally or purposefully find what you need to know?
I'm going to go out on a limb here and say that startups should be investing spare cycles in automation moreso than documentation.
Do you want a 100 page install guide or a fully automated install script? Which one is more likely to be kept up to date? Which one is more likelybto have people notice it's out of date and fix it? Documentation is helpful, but automation is a force multiplier.
It’s not just startups. I’ve been working in “The Enterprise” for 28 years and with one or two exceptions, my time would have been better spent automating internal processes that were documented than working on the actual product. And by better spent I mean the money saved in person hours manually and many times errantly repeating tasks that could have been done by software, exceeded any revenue generated from the product software I was working on.
Having just experienced a startup that attempted to do what you suggest, I will say that in this case, it did not work. First of all, there is so much more institutional knowledge to document than just installing something. Second of all, the first step in automating something complex is to document what it is to document.
If there is no documentation for the system architecture or how to solve common problems, everyone on the team wastes cycles solving problems that others already have, and doing it in different ways, so the codebase becomes an inconsistent pile.
Documentation is truly a force multiplier. It allows an entire team to learn from the experience of a single person, and that person can help the others passively and asynchronously.
If there is no documentation for the system architecture or how to solve common problems, everyone on the team wastes cycles solving problems that others already have, and doing it in different ways, so the codebase becomes an inconsistent pile.
Documentation is truly a force multiplier. It allows an entire team to learn from the experience of a single person, and that person can help the others passively and asynchronously.
I write automation constantly as my full time job. Documentation of how to do processes manually is definitely ripe to be automated.
But what parameters are available for the automation? Where does the automation live? How do you diagnose and improve when the automation breaks? Why did we even make this automation in the first place?
These sorts of questions are ripe for documentation. Most How style questions can be automated in one form or another. But the business process behind the automation, the context and domain knowledge around the autmation, for the humans who did not personally code it, documentation has major benefits that I think we as an industry don't value enough.
But what parameters are available for the automation? Where does the automation live? How do you diagnose and improve when the automation breaks? Why did we even make this automation in the first place?
These sorts of questions are ripe for documentation. Most How style questions can be automated in one form or another. But the business process behind the automation, the context and domain knowledge around the autmation, for the humans who did not personally code it, documentation has major benefits that I think we as an industry don't value enough.
> But what parameters are available for the automation?
A case of non-automatic automation :)
Actually, there's nothing wrong with that. Many things are best left that way. It's just an interesting oxymoron. And it's also interesting the fact that yours (and I'm sure many other's) mind jumped directly into it.
Automatic automations also exist. And those require a complete different set of documents.
But anyway, they are important because the "how do they work", "how do we fix (or improve) it", and "what can they do" are trivial to deduce from a working artifact. Those are not questions you usually want to answer with text.
A case of non-automatic automation :)
Actually, there's nothing wrong with that. Many things are best left that way. It's just an interesting oxymoron. And it's also interesting the fact that yours (and I'm sure many other's) mind jumped directly into it.
Automatic automations also exist. And those require a complete different set of documents.
But anyway, they are important because the "how do they work", "how do we fix (or improve) it", and "what can they do" are trivial to deduce from a working artifact. Those are not questions you usually want to answer with text.
> Do you want a 100 page install guide or a fully automated install script
Is there an example that actually happens? A system requiring 100 pages of documentation just for installing is not getting done in a single script
Is there an example that actually happens? A system requiring 100 pages of documentation just for installing is not getting done in a single script
Excellent point. Even as a non developer we are automating things like deploying databases for a application and complete system backups. We pay for that app to be developed but it pays off 200x once it's deployed and realized across all the like systems we manage.
When the automation breaks, and it always breaks: gimme that 100 page doc please
Some nice quotes in this article that center on the idea of finding a better tradeoff between on the one hand, documentation as a vehicle for knowledge sharing, and on the other hand, meetings as a vehicle for knowledge sharing (when they should be about decision making).
"You can think of Documentation as essentially the backbone of effective knowledge sharing."
"In the words of Bukowski, 'Don't do it unless it comes out of your soul like a rocket', apply the same principle to meetings."
"The constant need to have meetings is a symptom of a deeper problem — a lack of clear, accessible, and reliable documentation."
"Encourage your team to document their decision-making process to clarify assumptions, reasoning, and expected outcomes. Make it a standard practice to discuss these documented decisions in your meetings, promoting a culture of open feedback and collaborative decision-making."
"You can think of Documentation as essentially the backbone of effective knowledge sharing."
"In the words of Bukowski, 'Don't do it unless it comes out of your soul like a rocket', apply the same principle to meetings."
"The constant need to have meetings is a symptom of a deeper problem — a lack of clear, accessible, and reliable documentation."
"Encourage your team to document their decision-making process to clarify assumptions, reasoning, and expected outcomes. Make it a standard practice to discuss these documented decisions in your meetings, promoting a culture of open feedback and collaborative decision-making."
All this assumes one important thing: That people will read what you put in front of them.
I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate.
People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket that says exactly what is happening and lists the ten things I've already tried to resolve it. 100% of the time, the first reply is to ask if I've tried doing any of the first three things I said I already tried.
It's that kind of thing that makes me think documentation is hopeless. Nobody's going to read it anyway.
I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate.
People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket that says exactly what is happening and lists the ten things I've already tried to resolve it. 100% of the time, the first reply is to ask if I've tried doing any of the first three things I said I already tried.
It's that kind of thing that makes me think documentation is hopeless. Nobody's going to read it anyway.
I hate how true this is at most companies I have worked at. Invest a good amount of time writing up the docs and then a few hours later some asshole from another department has the nerve to ask me to “walk me through the process”.
Fuck you. I’ll leave you unread until end of day then send you the docs you clearly didn’t read.
Fuck you. I’ll leave you unread until end of day then send you the docs you clearly didn’t read.
People do not read what you write.
Then you need to move on, and find different people.
Yes -- I know it's tough. The landscape out there is quite bleak, in fact.
But these places, and these people do exist.
Then you need to move on, and find different people.
Yes -- I know it's tough. The landscape out there is quite bleak, in fact.
But these places, and these people do exist.
[deleted]
whenever i run across this issue i literally just cut and paste (or screenshot selection) what i wrote before. you have to deal with the reality you are presented with, and unfortunately in this reality nobody reads a damn thing, or they skip every other line, or skip the middle n lines of a big chunk, or whatever.
The thing that seems to come out of all these conversations is to treat documentation as UI/UX.
Maybe the problem is that it is treated as a secondary activity for developers, when it should be treated as a primary activity for writers.
We don't expect developers to be good at graphic design and even UI/UX design. In fact we should expect them to be terrible at it. A developer looks at the product from the inside, he sees classes, databases schemas, etc... not the way an end user will look at it. It means he will be biased into having a UI match the code structure and not the user workflow. There is a reason UI/UX designer is a job title, it is not a secondary activity for coders. Some can do both, but it is a different job.
Documentation could be treated the same way. Have people specialized in writing documentation. People who are actually good writers. I have seen it happen occasionally, and let me tell you, when you put a good writer (coding skills optional) in charge of writing documentation, the difference is night and day. Just as how better your UI will be when done by a good UI designer, and by a good UI designer, I mean someone who actually designs for usability, not someone who just tries to make something that looks cool for sales presentation, as it is too often the case for consumer apps today.
Maybe the problem is that it is treated as a secondary activity for developers, when it should be treated as a primary activity for writers.
We don't expect developers to be good at graphic design and even UI/UX design. In fact we should expect them to be terrible at it. A developer looks at the product from the inside, he sees classes, databases schemas, etc... not the way an end user will look at it. It means he will be biased into having a UI match the code structure and not the user workflow. There is a reason UI/UX designer is a job title, it is not a secondary activity for coders. Some can do both, but it is a different job.
Documentation could be treated the same way. Have people specialized in writing documentation. People who are actually good writers. I have seen it happen occasionally, and let me tell you, when you put a good writer (coding skills optional) in charge of writing documentation, the difference is night and day. Just as how better your UI will be when done by a good UI designer, and by a good UI designer, I mean someone who actually designs for usability, not someone who just tries to make something that looks cool for sales presentation, as it is too often the case for consumer apps today.
That angle is very good.
To me what's missing in many of these discussions is the cost/result calculation, how much effect is expected from "documentation". Thinking of it as an UX/UI could help put it more in terms of what time is spend by which user to achieve which specific task.
If specific use cases can be described, what needs to be written down becomes a lot more obvious and it can be done way more efficiently than just blindly "documenting" a system.
To me what's missing in many of these discussions is the cost/result calculation, how much effect is expected from "documentation". Thinking of it as an UX/UI could help put it more in terms of what time is spend by which user to achieve which specific task.
If specific use cases can be described, what needs to be written down becomes a lot more obvious and it can be done way more efficiently than just blindly "documenting" a system.
100% this. And yes, good documentation takes a lot of investment but it pays off like compound interest. But with that done, it becomes even more important not to pull the carpet for no good reason, you are building a tower and documentation is at the foundation.
We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then jump to the docs. This investment keeps on paying of as we use Lowdefy to build customer apps, new devs in the team typically take less than two week to get up to speed and start making contributions, the sharp ones, just a two or three days.
This year, we’re extended our documentation onto customer apps aswell, with flow diagrams, state machine definitions, detailed field level explication schema definitions, and end user test procedures. The key here for this documentation is detail. It should be easier to reach for the docs and the the answer, than to dive in the code and interpret it.
1 - https://github.com/lowdefy/lowdefy
We’ve built Lowdefy [1] as an open source project and documented it with all effort, 200 pages of docs. I often forget why or how something works and then jump to the docs. This investment keeps on paying of as we use Lowdefy to build customer apps, new devs in the team typically take less than two week to get up to speed and start making contributions, the sharp ones, just a two or three days.
This year, we’re extended our documentation onto customer apps aswell, with flow diagrams, state machine definitions, detailed field level explication schema definitions, and end user test procedures. The key here for this documentation is detail. It should be easier to reach for the docs and the the answer, than to dive in the code and interpret it.
1 - https://github.com/lowdefy/lowdefy
It is important to add to this a culture of actually reading the docs. Kudos here to my co-founder Sam. First developer I’ve ever met that reads ALL the docs before touching a line of code. When we say let’s pick up some tech, he dives in and reads every page of doc he finds. The effect saves time and results in much much better technical decisions. You don’t get stuck in the unknown, you immediately know where to go look if you are unsure, and architect a better big picture.
This, given of course that the tech you are picking up has good docs.
This, given of course that the tech you are picking up has good docs.
I wish reading docs more or less fully was more normalised. Time and again I find myself suddenly the, or close to the subject matter expert just because I actually read the documentation of what everyone else had already been working with for years, but was new to me. I don’t consider knowing a technology or tool without that step.
As you said, without it, you’re in the dark, doing guesswork. Doing that with multiple people, like a call with everyone guessing, is even worse. Just have everyone read the docs on their own time. So valuable.
As you said, without it, you’re in the dark, doing guesswork. Doing that with multiple people, like a call with everyone guessing, is even worse. Just have everyone read the docs on their own time. So valuable.
Whats the point in reading thousands of pages of documenation for an ephemeral and constantly changing project? In order to justify deep dives, the software itself has to be stable enough. I plan to read the entirety of the ANSI C specification for instance; it is a justified endeavour because ansi C is a stable standard with compilers implementing it for a long while. For a constantly changing project of course documenation is still important but it should be more geared toward quickly cluing you in on the specific part you are interested in, and hopefully make diffs easily presented and available.
Documentation is controversial because
(a) it's an ambiguous material (like wood), so anecdata go all ways
(b) it's for the future, i.e., easy to cut in a time pinch
(c) it presumes knowledge is shared, though it's often hoarded
(d) it's a tax on everyone's time
A helpful discussion of documentation would focus on specific use-cases: on-boarding developers, backgrounding design discussions, operational run-books...
In that context
(a) The cost/benefit is concrete
(b) You've identified the consumer/stakeholder, so they can speak the the present value
(c) Present work is value in terms of that future product
Then some documentation strategies become clear:
(1) Write for some specific reader. It's not a brain dump (unless it is, e.g., for departing engineer).
(2) Build in feedback cycles with actual users before completion
(3) Make it someone's job (put them on the hook) to deliver good documentation (for all users). They can optimize extraction and repurposing across the organization.
If I see director+ level people with no strategies for documentation, I conclude they're not building an organization.
(a) it's an ambiguous material (like wood), so anecdata go all ways
(b) it's for the future, i.e., easy to cut in a time pinch
(c) it presumes knowledge is shared, though it's often hoarded
(d) it's a tax on everyone's time
A helpful discussion of documentation would focus on specific use-cases: on-boarding developers, backgrounding design discussions, operational run-books...
In that context
(a) The cost/benefit is concrete
(b) You've identified the consumer/stakeholder, so they can speak the the present value
(c) Present work is value in terms of that future product
Then some documentation strategies become clear:
(1) Write for some specific reader. It's not a brain dump (unless it is, e.g., for departing engineer).
(2) Build in feedback cycles with actual users before completion
(3) Make it someone's job (put them on the hook) to deliver good documentation (for all users). They can optimize extraction and repurposing across the organization.
If I see director+ level people with no strategies for documentation, I conclude they're not building an organization.
We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore).
We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.
There's no existing documentation, save for 30,000+ JIRA tickets over a 5-year period, that describe various bug fixes and change requests. But those tickets are just floating in the ether and are not formally attached to any specific component, let alone route.
I was hoping AI would help but I can't seem to find anything relevant.
What would you do?
We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.
There's no existing documentation, save for 30,000+ JIRA tickets over a 5-year period, that describe various bug fixes and change requests. But those tickets are just floating in the ether and are not formally attached to any specific component, let alone route.
I was hoping AI would help but I can't seem to find anything relevant.
What would you do?
I would go from the most pressing problem, apply the Pareto principle to solve it, and repeat until reasonably happy. What is the biggest actual pain that the current lack of docs causes? I do not yet know the answer (feel free to share), but there is a good chance that the problem does not actually require a formal description of every screen one by one. You may be trying to create reference docs where higher level and more abstract documentation is warranted.
What would you do?
Accept that it's a big job and just get on with it. Sometimes we just have to do hard things. Putting it off or looking for a shortcut doesn't always work.
I'd also spend a couple of months seeing how much of the documentation production I can automate though. That's a small investment in a 700 day project.
Accept that it's a big job and just get on with it. Sometimes we just have to do hard things. Putting it off or looking for a shortcut doesn't always work.
I'd also spend a couple of months seeing how much of the documentation production I can automate though. That's a small investment in a 700 day project.
Yeah. There's this quote I love:
> If you have a mountain of shit to move, how much time should you spend looking for a bigger shovel? There's no obviously correct answer - it must depend on the size of the mountain, the availability of large shovels, how quickly you have to move it etc. But the answer absolutely cannot be 100% of your time. At some point you have to shovel some shit.
From https://www.scattered-thoughts.net/writing/things-unlearned/
> If you have a mountain of shit to move, how much time should you spend looking for a bigger shovel? There's no obviously correct answer - it must depend on the size of the mountain, the availability of large shovels, how quickly you have to move it etc. But the answer absolutely cannot be 100% of your time. At some point you have to shovel some shit.
From https://www.scattered-thoughts.net/writing/things-unlearned/
The corollary is also important. If you are writing code you should want it to solve a problem, and for it to be the chosen solution regularly. Make sure people with the problem you are solving know that your solution solves their problem, and how it solves their problem. That's the point of documentation.
Hire a couple of technical writers with experience and let them get on with it, and then make your devs document every new feature and change. Nothing passes code review unless it is accompanied by updated documentation. Getting your devs to document the existing codebase when you've inherited a shitshow like this will pull them away from their jobs for too long.
As a fellow Angular developer at a similar state of affairs, I am curious as to what problems you think documentation would solve, how you plan to maintain it after more "Jira tickets" layer up and what's your general strategy.
We hope it will save time when assessing bugs and describing new features, by providing a base reference of what the code currently does.
We intend to have designers update the doc when describing a change request, and the devs also update the doc afterwards.
We're not sure any of this is going to work; in the life of the project there has been at least two major documentation efforts, that failed because they were eventually abandoned (not maintained).
Some are still hoping there's some kind of magic bullet that would let us automate everything... and I'm not immune to this myself.
We intend to have designers update the doc when describing a change request, and the devs also update the doc afterwards.
We're not sure any of this is going to work; in the life of the project there has been at least two major documentation efforts, that failed because they were eventually abandoned (not maintained).
Some are still hoping there's some kind of magic bullet that would let us automate everything... and I'm not immune to this myself.
We're in a similarish situation. We decided to accept spending a bit of time on the documentation every time some JIRA ticket requires us to work on an undocumented section of code.
Not everything requires a lot of documentation, we have a lot of essentially glorified input dialogs, but we do try to write down what it is, and especially any logic and config settings that affect that logic.
One thing I've used before with success and which we've also introduced was two new fields in JIRA, "requires documentation update" and "documentation updated", to aid not forgetting to update documentation when adding or changing code.
Not everything requires a lot of documentation, we have a lot of essentially glorified input dialogs, but we do try to write down what it is, and especially any logic and config settings that affect that logic.
One thing I've used before with success and which we've also introduced was two new fields in JIRA, "requires documentation update" and "documentation updated", to aid not forgetting to update documentation when adding or changing code.
> If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.
It sounds like you're thinking about the really boring kind of documentation. The kind that no one wants to read and certainly no one wants to write.
In some approaches, the 4 types of documentation are tutorials, how-to guides, technical reference and explanation.
Any per-screen documentation is not tutorial, how-to or explanation. Perhaps it might be technical reference.
The first question then is why are you working on technical reference? Would you get more bang for the buck writing how-to guides?
It sounds like you're thinking about the really boring kind of documentation. The kind that no one wants to read and certainly no one wants to write.
In some approaches, the 4 types of documentation are tutorials, how-to guides, technical reference and explanation.
Any per-screen documentation is not tutorial, how-to or explanation. Perhaps it might be technical reference.
The first question then is why are you working on technical reference? Would you get more bang for the buck writing how-to guides?
We have docs and videos and whatnot, that describe how to use the application in order to accomplish a given task, in general terms (find some entry in the menu, go there, click that button).
What we do not have is something that describes exactly what the system is supposed to do, so that when one stumbles upon an unexpected behavior, they don't know if it's a bug or if it was intended that way (it could be either, depending on old requirements that weren't properly written down).
What we do not have is something that describes exactly what the system is supposed to do, so that when one stumbles upon an unexpected behavior, they don't know if it's a bug or if it was intended that way (it could be either, depending on old requirements that weren't properly written down).
do you have usage analytics or ticket token analytics? i would document the most commonly accessed/used stuff first.
and make sure this is at least one person's actual full-time job. chances are you'll have to hire specifically for this role because nobody wants to be bait-and-switched into this job, but there are actual professionals that do this for a living.
and make sure this is at least one person's actual full-time job. chances are you'll have to hire specifically for this role because nobody wants to be bait-and-switched into this job, but there are actual professionals that do this for a living.
Personally I think at the age of LLM lots of up-to-date documentation will be those superpowers that will boost some companies to whole new level.
Is it naive to assume that we could have bots actually read the code and come up with an "understanding" of what the code does instead of the metadata written by a human for humans on the side ?
Yup.
Were using LLM retrieval methods to build Q&A bots at work. These are all fed with documents (user guides, release notes, transcribed videos etc).
Its still very much POC but the interesting thing is people seems to care about documents again a bit more knowing that it will be used in this manner.
I was thinking about developing something that rewards document producers if their response is cited and used successfully - would help strengthen the feedback loop.
Were using LLM retrieval methods to build Q&A bots at work. These are all fed with documents (user guides, release notes, transcribed videos etc).
Its still very much POC but the interesting thing is people seems to care about documents again a bit more knowing that it will be used in this manner.
I was thinking about developing something that rewards document producers if their response is cited and used successfully - would help strengthen the feedback loop.
Agreed, Chatbots will make it a lot easier for the discovery process of documentation.
I have moderate successful Java library. Problem with documentation is:
- it takes effort to write it
- there is a split between what documentation describes and reality
- it falls behind as new stuff develops, project gets forked, taken over...
My solution is to have code examples, that are part of unit tests. Separate folder that describes most common use cases. If documentation is wrong, project does not even compile or test fails. And I can always point to most current version of examples in git branch.
I really think any document beyond simple readme.md is overkill for most projects.
- it takes effort to write it
- there is a split between what documentation describes and reality
- it falls behind as new stuff develops, project gets forked, taken over...
My solution is to have code examples, that are part of unit tests. Separate folder that describes most common use cases. If documentation is wrong, project does not even compile or test fails. And I can always point to most current version of examples in git branch.
I really think any document beyond simple readme.md is overkill for most projects.
I've been creating software developer docs for decades. Most contain the following content:
About X Installing and configuring X Using X X Reference
Typically developer docs are created from the bottom up. The devs create the preliminary reference docs using special comments in their code.
Once they are through, I go through their comments and wordsmith them.
After the reference topics are written, I start adding a "guide" section. I like to call this the "How-to" section, which answers questions like: * How do I create Y * How can I ... and so on.
I try to answer two classes of questions: * Tasks that everyone does (create a client, ...) * Tasks that flummox a lot of people (talk to the folks manning the help desk)
Once I'm happy with these task-based topics, I'll create a simple "Hello world" tutorial. This topic helps the user know that they've successfully installed and configured the software.
Finally I'll write the installation and configuration section.
It's possible to work on more than one section at a time. In fact, I typically write a bunch of sample code to try out ideas before I create the guide and tutorial. If possible, I'll tidy up these code snippets and add them to the docs. Developers always ask for more code examples.
And speaking of which, if you do create a code example, please create an accompanying unit test. Don't make your users find out that version 1.1 broke your code example. That's your job.
doug in Seattle
About X Installing and configuring X Using X X Reference
Typically developer docs are created from the bottom up. The devs create the preliminary reference docs using special comments in their code.
Once they are through, I go through their comments and wordsmith them.
After the reference topics are written, I start adding a "guide" section. I like to call this the "How-to" section, which answers questions like: * How do I create Y * How can I ... and so on.
I try to answer two classes of questions: * Tasks that everyone does (create a client, ...) * Tasks that flummox a lot of people (talk to the folks manning the help desk)
Once I'm happy with these task-based topics, I'll create a simple "Hello world" tutorial. This topic helps the user know that they've successfully installed and configured the software.
Finally I'll write the installation and configuration section.
It's possible to work on more than one section at a time. In fact, I typically write a bunch of sample code to try out ideas before I create the guide and tutorial. If possible, I'll tidy up these code snippets and add them to the docs. Developers always ask for more code examples.
And speaking of which, if you do create a code example, please create an accompanying unit test. Don't make your users find out that version 1.1 broke your code example. That's your job.
doug in Seattle
I’ve worked at a few startups, 1 or 2 that grew large (from <50 people when I arrived to tens of thousands of staff around the world). If your sails do catch the wind and you have to scale up, then documentation is invaluable (that and automation). Documentation needs an owner though, because it generally has a half-life and decays over time. This kind of ownership has to be enforced.
"Documentation" as a term is almost catastrophically overloaded, and just "documenting" things is only half the battle. I'll take semi-documented systems if the information architecture is good; perfectly documented components in an unnavigable mess is no good if I can't find the document that would help me.
While I agree that docu is important I've seen my share of garbage poured into wikis and presented as the single source of truth. It takes a lot of time and effort to make docu meaningful and useful with the outlook that it's ignored and overlooked anyways. Quality documentation is expensive, and, if one invests heavily into it there must be a clear workflow path that makes following and reviewing docu mandatory. Documenting for the sole reason of existence of docu is counterproductive.
stale documentation is worse than no documentation
The cause of stale documentation? Not writing documentation.
According to this saying, the fix to stale documentation is (often implied) to not write documentation. Can't go stale if it doesn't exist!
The above saying is so often used as an excuse to write no documentation so much that while stale documentation can provide more acute pain than no documentation, the chronic pain of no documentation is a cure worse than the disease.
According to this saying, the fix to stale documentation is (often implied) to not write documentation. Can't go stale if it doesn't exist!
The above saying is so often used as an excuse to write no documentation so much that while stale documentation can provide more acute pain than no documentation, the chronic pain of no documentation is a cure worse than the disease.
Ah I can totally see how my simple statement can imply that I would advocate for no documentation. This wasn't my intention. I think it's important to provide all team members with resources and guidance on how to maintain documentation so that it doesn't go stale. Documentation requires extra time and maintenance but providing tools to decrease the effort to ensure that written documentation doesn't go stale is important for every technical team leader to do.
I often find that trying to document code or a product forces me to rethink how I wrote it. Sometimes it's easier to change the code to make the concept simple to grok, then to write the documentation for the hard to grok concept. This is a very good thing.
Companies in general should do much more writing. Writing forces you to think in ways that coding doesn't. For me it's much easier to spot a poorly thought out argument then a bug in code (not a 1 for 1 comparison).
Companies in general should do much more writing. Writing forces you to think in ways that coding doesn't. For me it's much easier to spot a poorly thought out argument then a bug in code (not a 1 for 1 comparison).
Documentation is where I go to find out the mental model behind the software.
“Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.”
— Fred Brooks
With the mental model of the software, I know where to go, where to look, how to change to fulfil my new requirements.
I am thinking of writing a fictional documentation for a fictional operating system or library or web framework and then see where that design takes me.
“Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.”
— Fred Brooks
With the mental model of the software, I know where to go, where to look, how to change to fulfil my new requirements.
I am thinking of writing a fictional documentation for a fictional operating system or library or web framework and then see where that design takes me.
One thing said in another article that has really stuck with me on documentation is that it helps you scale yourself. You can only have so many meetings and so many discussions everyday. Maybe manage 5-10 people tops.
With good documentation, it can be used to scale yourself beyond what you can personally do everyday, and it works really well when you can convince people to search for answers before asking
With good documentation, it can be used to scale yourself beyond what you can personally do everyday, and it works really well when you can convince people to search for answers before asking
Documentation can play a significant role in reducing support tickets by providing users with the necessary information and guidance to resolve common issues on their own.
To identify the hot topics on support tickets, the docs team can liaise with the customer support team to get the support tickets data and figure out the content strategy. The docs team can add sections like FAQ, troubleshooting, customization, and best practices to address the queries. This can yield in reducing future support tickets.
You also need help from the support team on this task. When a customer raises a query that is already present in the docs, they should share the response along with the respective docs page link. This action would help the customers identify that the docs page is up-to-date and their queries can be resolved through self-service rather than a support ticket.
To identify the hot topics on support tickets, the docs team can liaise with the customer support team to get the support tickets data and figure out the content strategy. The docs team can add sections like FAQ, troubleshooting, customization, and best practices to address the queries. This can yield in reducing future support tickets.
You also need help from the support team on this task. When a customer raises a query that is already present in the docs, they should share the response along with the respective docs page link. This action would help the customers identify that the docs page is up-to-date and their queries can be resolved through self-service rather than a support ticket.
Mmmm, we believe papers are not enough to document code. We use a lot REPLs in Lisp and python for that.
Most of the time, this means making things smaller and modularise those. It takes a lot of work and there is always an initial resistance from the team for doing it. But it doesn't take much for them to realise how powerful and useful those interfaces are once they are in place and work.
A paper alone with code is kind of dumb, you need something people can interact with by discovery, by doing, experimenting, just like we do as children with the world surrounding us.
Just having some explanation is not enough: People just don't understand things reading about them, but formulating hypothesis about their understanding and confronting those with reality.
Without them, people are not going to be understanding what you believe they are understanding, but their own idea, that is often totally wrong.
Most of the time, this means making things smaller and modularise those. It takes a lot of work and there is always an initial resistance from the team for doing it. But it doesn't take much for them to realise how powerful and useful those interfaces are once they are in place and work.
A paper alone with code is kind of dumb, you need something people can interact with by discovery, by doing, experimenting, just like we do as children with the world surrounding us.
Just having some explanation is not enough: People just don't understand things reading about them, but formulating hypothesis about their understanding and confronting those with reality.
Without them, people are not going to be understanding what you believe they are understanding, but their own idea, that is often totally wrong.
I believe documentation can be highly beneficial, but only when it's done well. The article makes some good points on this, but, just based on experience and common sense, documentation should be centralized, clean and descriptive enough, while not being too wordy or plain gibberish.
That's not easy to achieve and takes time and resources to get right. That's primarly why so many fail or give up on it.
The results can very much be worth the effort, however, the ones who should be responsible for the documenting process likely don't see its importance. From their perspective, what they've worked on is easy to understand and requires little to no explanation. Taking time to change this mindset and create proper documentation is an effort many are unwilling to take.
That's not easy to achieve and takes time and resources to get right. That's primarly why so many fail or give up on it.
The results can very much be worth the effort, however, the ones who should be responsible for the documenting process likely don't see its importance. From their perspective, what they've worked on is easy to understand and requires little to no explanation. Taking time to change this mindset and create proper documentation is an effort many are unwilling to take.
> In the words of Bukowski, "Don't do it unless it comes out of your soul like a rocket,"
Given that Bukowski said that about writing, it applies more to writing documentation, than to holding meetings. So exactly the other way around than presented in this article.
Given that Bukowski said that about writing, it applies more to writing documentation, than to holding meetings. So exactly the other way around than presented in this article.
The real reason to write good (or at least minimally viable) documentation? The person who's going to need it most is Future You. When Future You has to return to a project a year after you last looked at things, you will than Past You for writing things down.
Problem with documentation is that there are a lot of uses for documentation. It can be a reference, it can describe the architecture, it can do many things. Probably a good idea to figure out what the intent is first to find a good form.
Some of my stuff is pretty sprawling, I've started integrating the documentation with the code and basically use readme.md's littered in the code as sign-posts to let you navigate it more quickly. The intent of that documentation is pretty clear, and the shape follows logically.
e.g. https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...
Some of my stuff is pretty sprawling, I've started integrating the documentation with the code and basically use readme.md's littered in the code as sign-posts to let you navigate it more quickly. The intent of that documentation is pretty clear, and the shape follows logically.
e.g. https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...
Hesitant though I am to recommend an approach to structuring documentation which needs its own documentation, the structure followed by the Django docs is straightforward to apply: https://mattsegal.dev/how-to-read-django-docs.html
I think the most important message of this blog post is this:
“ Designating a dedicated team or individual for documentation in an early-stage startup can seem extravagant. But trust me, it’s one of the smartest investments you can make. Why? Because knowledge is the lifeblood of your startup, and a dedicated handbook team acts as the circulatory system, ensuring that this vital knowledge flows freely and efficiently throughout the organization.”
So many startups lack technical writers, let alone docs teams. Not even OpenAI has one, as far as I know.
“ Designating a dedicated team or individual for documentation in an early-stage startup can seem extravagant. But trust me, it’s one of the smartest investments you can make. Why? Because knowledge is the lifeblood of your startup, and a dedicated handbook team acts as the circulatory system, ensuring that this vital knowledge flows freely and efficiently throughout the organization.”
So many startups lack technical writers, let alone docs teams. Not even OpenAI has one, as far as I know.
> Do you know how sometimes there are articles that have a 2000-word introduction to that one sentence that you need to solve your problem? That’s what over-documenting can feel like.
Good reminder.
Good reminder.
It was mentioned in a bullet point in the article a table of contents is really, really important if you want people to read your README. This is usually a no-brainer for libraries but I'm talking about company's repos for the applications they are developing. Often the READMEs are quite long and ain't no way anyone is going to scroll through an entire README in hopes that their question might be answered.
Suprise ? I thought documentation driven development is already the norm nowdays ? Is there other ways to do software development without documentation first ?
Yes? Think of a few requirements, open an editor and try it out in code. Compile, put in front of users or colleagues, get suggestions, repeat. No docs necessary whatsoever. Half the world works like this.
In my experience, documentation becomes outdated and fragmented very fast. If I had a say, I would make a rule that every employee should maintain only up to 10 wiki single-pages for their most important products, components or processes. At the top I would require a system overview diagram. And no details, only high-level concepts, keywords, pointers, links and contacts.
Can you show us "definition of done" for your process of closing a ticket? It looks like the "* [ ] update relevant documentation and list link to the documentation changeset" step is missed.
I'm big on documentation, but it needs to be done correctly.
I have a bit of a screed on the topic, that I did, a while back: https://littlegreenviper.com/miscellany/leaving-a-legacy/
I have a bit of a screed on the topic, that I did, a while back: https://littlegreenviper.com/miscellany/leaving-a-legacy/
[deleted]
The only place where I’ve seen documentation done well was where it was enforced. For ex: if you’re adding a new analytics tracking event, it must have corresponding documentation in internal wiki or build fails. It was annoying step but it enforced reliability of this wiki.
In my experience, the only people who benefit from good documentation are the highly competent. The corporate slugs who need Stack Overflow and GitHub Copilot to accomplish anything are still going to bother others every single day. At best you can point them to the documentation when this happens, but if their problem differs even slightly from what is documented, they will need additional hand holding. They also love to use the lack of documentation as an excuse for why they can't get things done, but then expect others to figure things out without documentation for them. If you write documentation, they still won't read it and will remain helpless.
First and foremost, who are you talking to?
Second, keep it plain and succinct. No convolution. No wordwalls.
Third. Use pictures and diagrams whenever possible.
(From my father, a technical writer of some renown.)
Second, keep it plain and succinct. No convolution. No wordwalls.
Third. Use pictures and diagrams whenever possible.
(From my father, a technical writer of some renown.)
Along these lines it was a shocking experience for me to to to use FastAI. Their documentation is incredibly poor (imo).
I think ChatGPT is going to become relevant in this space somehow.
Most software documentation is:
- the part of the software you didn't have the developer resources to implement
- so you decide to write documentation to have the "code" that runs on the user's brain
omg if someone could just put some notes in their code... that would be a wonderful start...
You should write three types of documentation. One for users, one for admins and one about architecture.
User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain tech was chosen, etc.
There's nothing that makes documentation more useless than when you're trying to do something like install the software but you have to dig thru piles of docs about why Postgres was chosen over MySQL. If your users or admins cant find the info they need quickly, they'll soon discard the documentation and user/system ops will go back to word of mouth knowledgeable.
I really think good companies focus on this and those who are successful really shine.