13 ms·

The Surprising Power of Documentation

343 points by bndr 3y ago

swayvil 3y ago
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.)
SoftTalker 3y ago
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.
- bruce511 3y ago
  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.
  - beachy 3y ago
    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-documentation/ 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.
  - pacaro 3y ago
    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.
  - remoquete 3y ago
    You also need technical writers.
- eviks 3y ago
  another key word is "searchable" documentation, and that's where man pages fail big time leading you to the likes of Google
  - sarnowski 3y ago
    What degree of „searchable“ are you missing from apropos? https://man.openbsd.org/apropos.1 https://man.openbsd.org/apropos.1
    - eviks 3y ago
      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
      - BLanen 3y ago
        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.
- makeitdouble 3y ago
  > 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.
  - allknowingfrog 3y ago
    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/ https://xkcd.com/1205/
- euroderf 3y ago
  Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".
gervwyk 3y ago
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 https://github.com/lowdefy/lowdefy
- gervwyk 3y ago
  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.
  - diarrhea 3y ago
    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.
franciscop 3y ago
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/ https://documentation.page/ and https://documentation.agency/ https://documentation.agency/ * (only 2 "negative" paragraphs on a book-length article)
- atoav 3y ago
  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.
briffid 3y ago
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
bambax 3y ago
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?
- onion2k 3y ago
  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.
  - bambax 3y ago
    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/ https://www.scattered-thoughts.net/writing/things-unlearned/
    - paddy_m 3y ago
      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.
antupis 3y ago
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.
- monkeydust 3y ago
  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.
- hahnbee 3y ago
  Agreed, Chatbots will make it a lot easier for the discovery process of documentation.
- makeitdouble 3y ago
  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 ?
63 3y ago
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.
- mailund 3y ago
  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?
  - c00lio 3y ago
    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.
    - underdeserver 3y ago
      Well, we have Whisper now, so you can transcribe them and search.
- elmolino89 3y ago
  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.
cracrecry 3y ago
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.
deleted 3y ago
[deleted]
pixel3234 3y ago
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.
realjohng 3y ago
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.
revskill 3y ago
Suprise ? I thought documentation driven development is already the norm nowdays ? Is there other ways to do software development without documentation first ?
- c00lio 3y ago
  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.
LT_SPA 3y ago
> 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.
dschuetz 3y ago
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.
- hahnbee 3y ago
  stale documentation is worse than no documentation
  - Multicomp 3y ago
    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.
    - hahnbee 3y ago
      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.
rho4 3y ago
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.
- oneshtein 3y ago
  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.
samsquire 3y ago
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.
marginalia_nu 3y ago
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/master/code#code https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...
- regularfry 3y ago
  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 https://mattsegal.dev/how-to-read-django-docs.html
nickdothutton 3y ago
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.
yxre 3y ago
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
regularfry 3y ago
"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.
kartanaangel 3y ago
[flagged]
euroderf 3y ago
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."
smeej 3y ago
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.
- lisasays 3y ago
  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.
  - deleted 3y ago
    [deleted]
- xyst 3y ago
  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.
- inconceivable 3y ago
  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.
arek_nawo 3y ago
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.
Lutger 3y ago
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.
- mewpmewp2 3y ago
  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.
  - Cthulhu_ 3y ago
    > 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.
    - makeitdouble 3y ago
      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.
SkipperCat 3y ago
I can't stress this enough. Know your audience and tailor your documentation to them. 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.
- Cthulhu_ 3y ago
  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).
  - syntheweave 3y ago
    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.
auggierose 3y ago
> 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.
ChrisMarshallNY 3y ago
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/ https://littlegreenviper.com/miscellany/leaving-a-legacy/
ConcernedCoder 3y ago
omg if someone could just put some notes in their code... that would be a wonderful start...
sodapopcan 3y ago
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.
entropyie 3y ago
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.
- 0x445442 3y ago
  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.
- Maxburn 3y ago
  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.
- Multicomp 3y ago
  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.
  - marcosdumay 3y ago
    > 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.
GuB-42 3y ago
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.
- makeitdouble 3y ago
  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.
paddy_m 3y ago
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).
eschneider 3y ago
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.
w10-1 3y ago
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.
manicennui 3y ago
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.
bjornasm 3y ago
Along these lines it was a shocking experience for me to to to use FastAI. Their documentation is incredibly poor (imo).
remoquete 3y ago
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.
SnoopDougDoug 3y ago
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
Prashanth_R 3y ago
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.
jononomo 3y ago
I think ChatGPT is going to become relevant in this space somehow.

343 points by bndr 3y ago

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.)

SoftTalker 3y ago

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.

bruce511 3y ago
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.
- beachy 3y ago
  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-documentation/ 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.
- pacaro 3y ago
  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.
- remoquete 3y ago
  You also need technical writers.
eviks 3y ago
another key word is "searchable" documentation, and that's where man pages fail big time leading you to the likes of Google
- sarnowski 3y ago
  What degree of „searchable“ are you missing from apropos? https://man.openbsd.org/apropos.1 https://man.openbsd.org/apropos.1
  - eviks 3y ago
    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
    - BLanen 3y ago
      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.
makeitdouble 3y ago
> 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.
- allknowingfrog 3y ago
  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/ https://xkcd.com/1205/
euroderf 3y ago
Agreed on your last paragraph. One of my mantras to coders, as a tech documentarian, was that "Incorrect documentation is worse than no documentation".

gervwyk 3y ago

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 https://github.com/lowdefy/lowdefy

gervwyk 3y ago
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.
- diarrhea 3y ago
  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.

franciscop 3y ago

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/ https://documentation.page/ and https://documentation.agency/ https://documentation.agency/ * (only 2 "negative" paragraphs on a book-length article)

atoav 3y ago
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.

briffid 3y ago

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

bambax 3y ago

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?

onion2k 3y ago
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.
- bambax 3y ago
  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/ https://www.scattered-thoughts.net/writing/things-unlearned/
  - paddy_m 3y ago
    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.

antupis 3y ago

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.

monkeydust 3y ago
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.
hahnbee 3y ago
Agreed, Chatbots will make it a lot easier for the discovery process of documentation.
makeitdouble 3y ago
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 ?

63 3y ago

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.

mailund 3y ago
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?
- c00lio 3y ago
  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.
  - underdeserver 3y ago
    Well, we have Whisper now, so you can transcribe them and search.
elmolino89 3y ago
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.

cracrecry 3y ago

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.

deleted 3y ago

[deleted]

pixel3234 3y ago

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.

realjohng 3y ago

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.

revskill 3y ago

Suprise ? I thought documentation driven development is already the norm nowdays ? Is there other ways to do software development without documentation first ?

c00lio 3y ago
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.

LT_SPA 3y ago

> 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.

dschuetz 3y ago

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.

hahnbee 3y ago
stale documentation is worse than no documentation
- Multicomp 3y ago
  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.
  - hahnbee 3y ago
    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.

rho4 3y ago

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.

oneshtein 3y ago
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.

samsquire 3y ago

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.

marginalia_nu 3y ago

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/master/code#code https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...

regularfry 3y ago
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 https://mattsegal.dev/how-to-read-django-docs.html

nickdothutton 3y ago

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.

yxre 3y ago

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

regularfry 3y ago

"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.

kartanaangel 3y ago

[flagged]

euroderf 3y ago

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."

smeej 3y ago

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.

lisasays 3y ago
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.
- deleted 3y ago
  [deleted]
xyst 3y ago
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.
inconceivable 3y ago
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.

arek_nawo 3y ago

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.

Lutger 3y ago

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.

mewpmewp2 3y ago
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.
- Cthulhu_ 3y ago
  > 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.
  - makeitdouble 3y ago
    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.

SkipperCat 3y ago

I can't stress this enough. Know your audience and tailor your documentation to them. 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.

Cthulhu_ 3y ago
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).
- syntheweave 3y ago
  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.

auggierose 3y ago

> 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.

ChrisMarshallNY 3y ago

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/ https://littlegreenviper.com/miscellany/leaving-a-legacy/

ConcernedCoder 3y ago

omg if someone could just put some notes in their code... that would be a wonderful start...

sodapopcan 3y ago

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.

entropyie 3y ago

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.

0x445442 3y ago
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.
Maxburn 3y ago
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.
Multicomp 3y ago
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.
- marcosdumay 3y ago
  > 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.

GuB-42 3y ago

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.

makeitdouble 3y ago
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.

paddy_m 3y ago

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).

eschneider 3y ago

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.

w10-1 3y ago

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.

manicennui 3y ago

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.

bjornasm 3y ago

Along these lines it was a shocking experience for me to to to use FastAI. Their documentation is incredibly poor (imo).

remoquete 3y ago

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.

SnoopDougDoug 3y ago

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

Prashanth_R 3y ago

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.

jononomo 3y ago

I think ChatGPT is going to become relevant in this space somehow.