3 ms·

> Documentation only works up to a point because it can both get out of sync with what the code is doing and because documenting the internals of a complex piec

> Documentation only works up to a point because it can both get out of sync with what the code is doing and because documenting the internals of a complex piece of software is a rare skill. A skill that most developers don’t possess. Most internal documentation only begins to make sense to a developer after they’ve developed an internal mental model of how it all hangs together. Most code documentation becomes useful after you have built the theory in your mind, not before. It operates as a mnemonic for what you already know, not as a tool for learning. This is ringing particularly true to me right now. The organization I work for has allowed bit rot to occur for a number of years, to the point that it's becoming increasingly common for things to break whenever even seemingly small changes are implemented. The "solution" that we've implemented is to require a detailed RFC document whenever you want to create or modify anything. You're required to outline every anticipated step along the way, all the tiny minutiae that you foresee yourself encountering and how you'll deal with it. And in a Google doc, no less. It's utterly exhausting.

tikiman163 4y ago
I'm not a huge fan of writing a ton of documentation about the code. I am a huge fan of requiring developers to write in-line comments explaining what they're doing so the next person can build that internal model more easily. There should be some documentation about the system, but this is much more helpful if it only explains how to get the project running locally, including configuration settings and how to interact with it (if data has to be uploaded for a process, what should the data look like and how do you upload it). From there, a mid level developer should be able to locate the code entry points and follow the online comments to find what they need. Just because it seemed obvious what you were doing and how things worked while you were writing the code doesn't mean it is, or that it will stay that way. Especially if that code ends up getting abstracted out. In line comments demystify code for the next guy way better than any amount of well written documentation. As for what they're making you do with the RFC documents for changes, try writing your stuff as an ordered multi-tier list. The first tier should be the "manager" description of the change. The next level should be the more technical description of changes. The third tier is the location in the code where that change needs to be made (like a file path sort of thing, but you could use name spaces and even method names if you want). The forth and final tier if you need it would be cross references to other related items in the list and implementation notes/challenges specific to the file path. I've used this approach in the past myself. It's much faster, and it allows you to write a spec doc that isn't a huge waste of your time because it allows you to half write your code at the same time. It also provides a sort of semantic map from how the manager thinks about things to how you think about them, making it much easier for a manager to discuss it with you without having to write nearly as much. Another benefit to this is you can often use stuff from the second and forth tiers to add in line code comments.
birdyrooster 4y ago
Bit rot is such a crappy metaphor.
- cjbgkagh 4y ago
  Pretty sure it’s a metaphor. Edit: parent comment was edited.
  - birdyrooster 4y ago
    A bad one
    - cratermoon 4y ago
      Why is it bad? What's a better one? What would a better one look like?
      - tyingq 4y ago
        "context rot" is more aligned with what they are describing, though that's not a metaphor. I can see bitrot being a bad fit, as it's decay of the actual thing rather than the surrounding context.
        cratermoon 4y ago
        Except that implies the context has rotted, when in fact the context is fresher than the system within it. While the context may have degraded in some way, the reality is that it's changed according to forces that have acted on it since the code within it was written and deployed. What's rotted is the ability of the system to meaningfully and correctly interact with the context.
- bentobean 4y ago
  In this context, I'm using "bit rot" as a metaphor in the same way that the author does: > The first is that it’s a partial explanation for bitrot, the phenomenon where working software seems to deteriorate even when the code is untouched.
mr337 4y ago
That does sound horrid. Makes green field projects look ever more so nice.
- ahepp 4y ago
  Sure, but your greenfield project today will just be someone else's brownfield project in a couple years
sz4kerto 4y ago
Ruthless end-to-end testing helps. Really hard on the short term, pays back on the long term. The suite is the specification.
- naasking 4y ago
  100% this.
- bentobean 4y ago
  I agree. What about a situation wherein you have a QA team that stands entirely apart from the devs and they are the holders of the specification?
  - bluGill 4y ago
    Automate the tests. Sure the QA group holds the final say, but if you have a test that breaks you don't have to ask them. Or at least you have something to base a.conversation on. Note that requirements change, and bad tests will break on no requirements. Telling the difference is an exercise for the reader.
    - bentobean 4y ago
      The tests are automated… by the QA team. Using a web-based tool for which none of the devs have access.
      - ghotli 4y ago
        I see two ways forward, both probably not great advice. 1. Ask for forgiveness and do whatever you think is prudent regardless of org structure. 2. Find a better org structure elsewhere :)
        bentobean 4y ago
        I tend to agree. When I am capable of summoning the energy to care at this point, I make a run at #1. I have recently decided to actively pursue #2, as well.
mjevans 4y ago
Observationally, C and related languages frequently use headers as a documentation and API specification point. The internals aren't revealed, but the expectations are distilled into one easier to reference location. I know I appreciate that more than machine (only) readable blobs that expect auto-doc tools to split out the salient information with the technical signatures. The human curation also allows for ordering that matters to organics who must integrate related data, rather than just alphanumeric enumeration.
- midoridensha 4y ago
  >The internals aren't revealed They are when devs put all the code into those header files.
  - intelVISA 4y ago
    ...does that happen? Outside of C++ templates or inlining is there a need to pollute the header file?
    - midoridensha 4y ago
      A need? Definitely not. It's terrible practice. Does it happen? Absolutely, I've seen it many times. Why some C++ devs do this, I really don't know; I think it's just laziness.
windowshopping 4y ago
Do you work at Squarespace? This was exactly my experience there.
- bentobean 4y ago
  No.
dathinab 4y ago
Worse in my experience the quality of documentation (and tests) decreases the more a company is heading for insolvency for multiple overlapping reasons (at least for "startup| like companies). This means if you want to buy a struggling or insolvent company it will most likely have bad documentation and tests. But one of the most common steps when buying a struggling company is firing people (making the company fire people before buying it) and the selection of who goes and stays is rarely a good one. And it sets signals which make it mote likely for further important people to quit.
- midoridensha 4y ago
  I think the reason to buy a struggling company is simply to get access to its IP (patents mainly) and customers, not to take over its operations. If it's struggling, it was already doing things badly and probably can't be saved. Usually, when I see tech companies purchased, it's because the company wasn't struggling: it was doing quite well, but was small, so a much larger company bought it up in an acquisition to add its capabilities to their own, like the Borg. The big company gets IP, customers, revenue, and an already-working business, while the founders get a big payout.
smeagull 4y ago
> The "solution" that we've implemented is to require a detailed RFC document whenever you want to create or modify anything. I'd suggest just using the documentation. Manuals get used for doing testing and implementation. Using the documentation is like testing for it, and finding those problems right away is the best way I've found to ensuring that the documentation is correct and up to date.
jerf 4y ago
"Most internal documentation only begins to make sense to a developer after they’ve developed an internal mental model of how it all hangs together. Most code documentation becomes useful after you have built the theory in your mind, not before. It operates as a mnemonic for what you already know, not as a tool for learning." This reveals the secret goal of documentation: To build that model, not to document every last detail. The code can do every last detail, it's the model that is hard. Set out with that goal and... yeah, I can't guarantee success for you either. It's a fundamentally challenging task. But at least you'll be off to a better start than if you think the primary purpose of documentation is to document what happens if you set this combination of flags. That has its place too, certainly, but if I can only pick one, I'd take the high-quality high-level overview over the stuff I can read the code for in 30 seconds.
- galaxyLogic 4y ago
  The mental model really is not in the documentation, it is in the source-code modules how they interact with each other. Therefore I think OOP is a great way for building software. you need to create a mental imaginary world where the objects exist and interact. Then it makes sense. But like you say it is challenging, even finding good names is hard. But basically, can you write a story about the software working, that would allow readers to understand it? Create user-stories but not (only) about the users but understanding that any module is a "user" of its components.
  - sirmarksalot 4y ago
    The thing is every project has mistakes. Things that aren't where they're supposed to be, that somebody means to tidy up sometime later, but just hasn't gotten around to yet. Every project has at least a little bit of a mess somewhere. When all you have to go off of is the code itself, then can be hard to tell the difference between the mess and the design. A junior dev who comes in without much coaching, might just reference an anti-pattern from the "mess" section and replicate it throughout the code base. And then do that enough times, and a senior dev who gets brought in might conclude that there's no design at all, and that what it really needs is a rewrite.
cm2012 4y ago
Friction is the enemy of productivity. I guarantee that most employees simply decide not to mention ideas for projects that could help the company because of the headache. They will do the minimum needed to keep their jobs.
- bentobean 4y ago
  I know for a fact that this is true. Office Space was not a comedy - it was a documentary.
yarg 4y ago
I worked in an environment where a senior architect got to veto every major effort that I publically made to improve the structure and maintainability of the software. At some point I got so pissed off about this that I started assigning code reviews to him - he contacted my manager and asked that I stop, because he had no understanding of the project in question. What did this mean from the documentation side? I would have loved to accurately document what I was doing and how the project was structured - but I actively avoided doing so. Every time my manager's boss knew what I was doing, I was about to be shat on from great heights. Months of work and planning erased at the drop of a hat - time and time again. Dependency injection? Fuck off. Spring's too heavy. Modularity? Fuck off. The project's too small. Hierarchical profiles? Fuck you, keep using a properties file (with an increasing number of dynamically generated keys). I was constantly asking for a new developer to be brought in for the transfer of knowledge - at best I was told "That's not a bad idea."; yet nothing was ever done about it. I took an unmaintainable pile of bugs and made it stable and maintainable. But nothing I ever did meant that I was someone worth listening to. Eventually I got so burnt-out (and consumed by feelings of uselessness) that I walked away without finding another job. I was damned near suicidal from fighting for acknowledgement. I cannot imagine that my departure went too well for them.
- JAlexoid 4y ago
  Your comment is why everyone should start their engineering experience as a consultant. Primary thing that I learned being a consultant - you can leave and you don't have to suffer the disdain from the management. You learn to disconnect yourself and be replaceable. It makes for a less frustrating life. Sad that it happened to you. Don't invest yourself in someone else's child.
- andrewmcwatters 4y ago
  Here's the kicker, I hate to say it, but they probably didn't notice you left. That's the thing about places like that.
  - fatneckbeard 4y ago
    yeup. and realizing that is the only way to stay sane. nobody will care if you leave, nobody cared about the last person that left, they have other priorities and software engineering is not one of them. if its that much of a problem, their business will fail and some other business that does care will take over their market. but that might take decades because software engineering isn't actually core to a lot of business activity. youd be amazed at how bad some software is for major companies, and yet they are very profitable. you only have control over yourself not other people.
layer8 4y ago
> documenting the internals of a complex piece of software is a rare skill. A skill that most developers don’t possess. I believe this is partially due to lack of training (technical writing rarely gets trained, and companies rarely invest in it as a skill), and sometimes probably also due to lack of exposure to high-quality documentation (which serve as role models you’d then want to live up to in your own documentation). In addition, companies often do not reward expending time and effort on writing documentation, because it isn’t crucial in the short term. It’s similar to tech debt, just documentation debt. While writing good documentation isn’t easy, the fact that it usually gets neglected is a cultural issue.
- BlueTemplar 4y ago
  Any examples of great documentation ? (For open source of course.)
  - layer8 4y ago
    I have no particular recent examples in mind, though I believe the Rust documentation is pretty good. Maybe browse these search results where similar questions have been asked previously: https://hn.algolia.com/?query=documentation%20examples https://hn.algolia.com/?query=documentation%20examples
- BurningFrog 4y ago
  My take: People "on the spectrum" are not great communicators, and also struggle to understand what it is other people know and don't know. Also, documenting is genuinely hard, even if you don't consider that it changes all the time. Which it typically does.
  - layer8 4y ago
    I agree that not everyone has a knack for it. But I don’t think that’s the only factor. Software design/architecture is also hard and many devs aren‘t particularly good at it. We still recognize it as an important skill that requires education and training (and experience). If even just 20% or so of devs would get up to speed with how to write adequate documentation, and were enabled to invest the necessary time for it, that would already be a huge improvement.
tomcam 4y ago
> And in a Google doc, no less. That whole process sucks and I’m sorry you have to go through it. It’s probably the best solution of the time. My one question is… Isn’t that why we have github issues?
- bentobean 4y ago
  Because the pointy-haired bosses in product and all of the various managerial minions don’t have GitHub accounts, so it’s either that or (shudder) a Confluence page.
  - tomcam 4y ago
    My condolences to you and yours.
  - MathMonkeyMan 4y ago
    I think we work at the same company. Write your RFCs as markdown in a git repository. Stick it to the man!
coryrc 4y ago
"No" SWE ever got promoted for documenting someone else's code. Follow the incentives.
- sublinear 4y ago
  Huh? Documenting a terrible project is an excellent way to propose and volunteer yourself into a new project of your own design and ultimately get promoted into lead/architect/SME types of roles. I don't know anyone who has done it any other way.
  - nullsense 4y ago
    Yeah I've done this too.
hnick 4y ago
This is why I also didn't particularly enjoy answering questions concisely at my previous company. I still did, I just hated it. Documentation can describe a system state, and how to use or approach it, but in my experience it really lacks in capturing the full depth of experience when it comes to interacting with it. All the little shortcuts and workarounds. All the debugging steps. Seeing something, and realising you've seen it before and solving it in 5 minutes instead of the entire day it took you last time. I could write a story about that day, but it wouldn't do anyone any good - they won't learn from that experience like I did and it won't spring to mind instantly. Assuming they even know where to find a piece written about their specific problem. So when someone says "How do I X?" all I can think about is all the incidental things I've learned when trying to do something else. This builds the bigger picture. I can answer your question, but you'll just paste the code in and be back to ask more tomorrow. I valued the coworkers who treated such things as more of a discussion and learning opportunity than a transactional question-answer routine.
- perrygeo 4y ago
  > the full depth of experience when it comes to interacting with it. This is the part that most people conveniently forget. Many people find it easier to create elaborate docs and processes than to regularly interact with the software system they've built.
- deleted 4y ago
  [deleted]
- aorloff 4y ago
  This is why effective documentation starts with run books.
  - malandrew 4y ago
    I have a love-hate relationship with runbooks. I see them as tech debt for things you haven’t yet automated or made clear enough. If someone needs to go read a doc to understand what they need to do, you’re already behind.
GartzenDeHaes 4y ago
Management is about process, people, and resources. If you ask a manager to solve a problem, the solution will often be some combination of: - A defined and documented process - Project planning or organization changes - Staffing, purchasing, or contracting These are fine tools for a lot of business problems, but they are rarely helpful, and often harmful, for software development.
chii 4y ago
> outline every anticipated step along the way, all the tiny minutiae that you foresee yourself encountering and how you'll deal with it waterfall by any other name smells just as bad. I think the reason is that senior management has no trust in the developers, which is the ultimate cause of the need to have waterfall. Each reporting level wants to show concrete evidence that those under them are "doing their best", rather than to have trust that they are. Of course, it is understandable that people want concrete "evidence". But waterfall is the result, and you end up with big-bang designs, RFCs that are out of date because a change in circumstances necessitate a change that is not documented in an RFC. It is a management problem, not a software development problem, imho.
fexecve 4y ago
Most companies either do too little documentation (they have a little page with the bare minimum high-level overview), or they do way too much (detailed change request forms for every change, which go into a file cabinet, and are never looked at again). Alas, it's really hard to get people to understand that documentation is good and necessary when they've only ever been exposed to one or both of those systems.
deleted 4y ago
[deleted]
llamajams 4y ago
Y'all ain't work on projects with NO docs and no OG devs. I'll take an outdated Google doc over nothing and day of the week.

tikiman163 4y ago

I'm not a huge fan of writing a ton of documentation about the code. I am a huge fan of requiring developers to write in-line comments explaining what they're doing so the next person can build that internal model more easily. There should be some documentation about the system, but this is much more helpful if it only explains how to get the project running locally, including configuration settings and how to interact with it (if data has to be uploaded for a process, what should the data look like and how do you upload it). From there, a mid level developer should be able to locate the code entry points and follow the online comments to find what they need. Just because it seemed obvious what you were doing and how things worked while you were writing the code doesn't mean it is, or that it will stay that way. Especially if that code ends up getting abstracted out. In line comments demystify code for the next guy way better than any amount of well written documentation. As for what they're making you do with the RFC documents for changes, try writing your stuff as an ordered multi-tier list. The first tier should be the "manager" description of the change. The next level should be the more technical description of changes. The third tier is the location in the code where that change needs to be made (like a file path sort of thing, but you could use name spaces and even method names if you want). The forth and final tier if you need it would be cross references to other related items in the list and implementation notes/challenges specific to the file path. I've used this approach in the past myself. It's much faster, and it allows you to write a spec doc that isn't a huge waste of your time because it allows you to half write your code at the same time. It also provides a sort of semantic map from how the manager thinks about things to how you think about them, making it much easier for a manager to discuss it with you without having to write nearly as much. Another benefit to this is you can often use stuff from the second and forth tiers to add in line code comments.

birdyrooster 4y ago

Bit rot is such a crappy metaphor.

cjbgkagh 4y ago
Pretty sure it’s a metaphor. Edit: parent comment was edited.
- birdyrooster 4y ago
  A bad one
  - cratermoon 4y ago
    Why is it bad? What's a better one? What would a better one look like?
    - tyingq 4y ago
      "context rot" is more aligned with what they are describing, though that's not a metaphor. I can see bitrot being a bad fit, as it's decay of the actual thing rather than the surrounding context.
      - cratermoon 4y ago
        Except that implies the context has rotted, when in fact the context is fresher than the system within it. While the context may have degraded in some way, the reality is that it's changed according to forces that have acted on it since the code within it was written and deployed. What's rotted is the ability of the system to meaningfully and correctly interact with the context.
bentobean 4y ago
In this context, I'm using "bit rot" as a metaphor in the same way that the author does: > The first is that it’s a partial explanation for bitrot, the phenomenon where working software seems to deteriorate even when the code is untouched.

mr337 4y ago

That does sound horrid. Makes green field projects look ever more so nice.

ahepp 4y ago
Sure, but your greenfield project today will just be someone else's brownfield project in a couple years

sz4kerto 4y ago

Ruthless end-to-end testing helps. Really hard on the short term, pays back on the long term. The suite is the specification.

naasking 4y ago
100% this.
bentobean 4y ago
I agree. What about a situation wherein you have a QA team that stands entirely apart from the devs and they are the holders of the specification?
- bluGill 4y ago
  Automate the tests. Sure the QA group holds the final say, but if you have a test that breaks you don't have to ask them. Or at least you have something to base a.conversation on. Note that requirements change, and bad tests will break on no requirements. Telling the difference is an exercise for the reader.
  - bentobean 4y ago
    The tests are automated… by the QA team. Using a web-based tool for which none of the devs have access.
    - ghotli 4y ago
      I see two ways forward, both probably not great advice. 1. Ask for forgiveness and do whatever you think is prudent regardless of org structure. 2. Find a better org structure elsewhere :)
      - bentobean 4y ago
        I tend to agree. When I am capable of summoning the energy to care at this point, I make a run at #1. I have recently decided to actively pursue #2, as well.

mjevans 4y ago

Observationally, C and related languages frequently use headers as a documentation and API specification point. The internals aren't revealed, but the expectations are distilled into one easier to reference location. I know I appreciate that more than machine (only) readable blobs that expect auto-doc tools to split out the salient information with the technical signatures. The human curation also allows for ordering that matters to organics who must integrate related data, rather than just alphanumeric enumeration.

midoridensha 4y ago
>The internals aren't revealed They are when devs put all the code into those header files.
- intelVISA 4y ago
  ...does that happen? Outside of C++ templates or inlining is there a need to pollute the header file?
  - midoridensha 4y ago
    A need? Definitely not. It's terrible practice. Does it happen? Absolutely, I've seen it many times. Why some C++ devs do this, I really don't know; I think it's just laziness.

windowshopping 4y ago

Do you work at Squarespace? This was exactly my experience there.

bentobean 4y ago
No.

dathinab 4y ago

Worse in my experience the quality of documentation (and tests) decreases the more a company is heading for insolvency for multiple overlapping reasons (at least for "startup| like companies). This means if you want to buy a struggling or insolvent company it will most likely have bad documentation and tests. But one of the most common steps when buying a struggling company is firing people (making the company fire people before buying it) and the selection of who goes and stays is rarely a good one. And it sets signals which make it mote likely for further important people to quit.

midoridensha 4y ago
I think the reason to buy a struggling company is simply to get access to its IP (patents mainly) and customers, not to take over its operations. If it's struggling, it was already doing things badly and probably can't be saved. Usually, when I see tech companies purchased, it's because the company wasn't struggling: it was doing quite well, but was small, so a much larger company bought it up in an acquisition to add its capabilities to their own, like the Borg. The big company gets IP, customers, revenue, and an already-working business, while the founders get a big payout.

smeagull 4y ago

> The "solution" that we've implemented is to require a detailed RFC document whenever you want to create or modify anything. I'd suggest just using the documentation. Manuals get used for doing testing and implementation. Using the documentation is like testing for it, and finding those problems right away is the best way I've found to ensuring that the documentation is correct and up to date.

jerf 4y ago

"Most internal documentation only begins to make sense to a developer after they’ve developed an internal mental model of how it all hangs together. Most code documentation becomes useful after you have built the theory in your mind, not before. It operates as a mnemonic for what you already know, not as a tool for learning." This reveals the secret goal of documentation: To build that model, not to document every last detail. The code can do every last detail, it's the model that is hard. Set out with that goal and... yeah, I can't guarantee success for you either. It's a fundamentally challenging task. But at least you'll be off to a better start than if you think the primary purpose of documentation is to document what happens if you set this combination of flags. That has its place too, certainly, but if I can only pick one, I'd take the high-quality high-level overview over the stuff I can read the code for in 30 seconds.

galaxyLogic 4y ago
The mental model really is not in the documentation, it is in the source-code modules how they interact with each other. Therefore I think OOP is a great way for building software. you need to create a mental imaginary world where the objects exist and interact. Then it makes sense. But like you say it is challenging, even finding good names is hard. But basically, can you write a story about the software working, that would allow readers to understand it? Create user-stories but not (only) about the users but understanding that any module is a "user" of its components.
- sirmarksalot 4y ago
  The thing is every project has mistakes. Things that aren't where they're supposed to be, that somebody means to tidy up sometime later, but just hasn't gotten around to yet. Every project has at least a little bit of a mess somewhere. When all you have to go off of is the code itself, then can be hard to tell the difference between the mess and the design. A junior dev who comes in without much coaching, might just reference an anti-pattern from the "mess" section and replicate it throughout the code base. And then do that enough times, and a senior dev who gets brought in might conclude that there's no design at all, and that what it really needs is a rewrite.

cm2012 4y ago

Friction is the enemy of productivity. I guarantee that most employees simply decide not to mention ideas for projects that could help the company because of the headache. They will do the minimum needed to keep their jobs.

bentobean 4y ago
I know for a fact that this is true. Office Space was not a comedy - it was a documentary.

yarg 4y ago

I worked in an environment where a senior architect got to veto every major effort that I publically made to improve the structure and maintainability of the software. At some point I got so pissed off about this that I started assigning code reviews to him - he contacted my manager and asked that I stop, because he had no understanding of the project in question. What did this mean from the documentation side? I would have loved to accurately document what I was doing and how the project was structured - but I actively avoided doing so. Every time my manager's boss knew what I was doing, I was about to be shat on from great heights. Months of work and planning erased at the drop of a hat - time and time again. Dependency injection? Fuck off. Spring's too heavy. Modularity? Fuck off. The project's too small. Hierarchical profiles? Fuck you, keep using a properties file (with an increasing number of dynamically generated keys). I was constantly asking for a new developer to be brought in for the transfer of knowledge - at best I was told "That's not a bad idea."; yet nothing was ever done about it. I took an unmaintainable pile of bugs and made it stable and maintainable. But nothing I ever did meant that I was someone worth listening to. Eventually I got so burnt-out (and consumed by feelings of uselessness) that I walked away without finding another job. I was damned near suicidal from fighting for acknowledgement. I cannot imagine that my departure went too well for them.

JAlexoid 4y ago
Your comment is why everyone should start their engineering experience as a consultant. Primary thing that I learned being a consultant - you can leave and you don't have to suffer the disdain from the management. You learn to disconnect yourself and be replaceable. It makes for a less frustrating life. Sad that it happened to you. Don't invest yourself in someone else's child.
andrewmcwatters 4y ago
Here's the kicker, I hate to say it, but they probably didn't notice you left. That's the thing about places like that.
- fatneckbeard 4y ago
  yeup. and realizing that is the only way to stay sane. nobody will care if you leave, nobody cared about the last person that left, they have other priorities and software engineering is not one of them. if its that much of a problem, their business will fail and some other business that does care will take over their market. but that might take decades because software engineering isn't actually core to a lot of business activity. youd be amazed at how bad some software is for major companies, and yet they are very profitable. you only have control over yourself not other people.

layer8 4y ago

> documenting the internals of a complex piece of software is a rare skill. A skill that most developers don’t possess. I believe this is partially due to lack of training (technical writing rarely gets trained, and companies rarely invest in it as a skill), and sometimes probably also due to lack of exposure to high-quality documentation (which serve as role models you’d then want to live up to in your own documentation). In addition, companies often do not reward expending time and effort on writing documentation, because it isn’t crucial in the short term. It’s similar to tech debt, just documentation debt. While writing good documentation isn’t easy, the fact that it usually gets neglected is a cultural issue.

BlueTemplar 4y ago
Any examples of great documentation ? (For open source of course.)
- layer8 4y ago
  I have no particular recent examples in mind, though I believe the Rust documentation is pretty good. Maybe browse these search results where similar questions have been asked previously: https://hn.algolia.com/?query=documentation%20examples https://hn.algolia.com/?query=documentation%20examples
BurningFrog 4y ago
My take: People "on the spectrum" are not great communicators, and also struggle to understand what it is other people know and don't know. Also, documenting is genuinely hard, even if you don't consider that it changes all the time. Which it typically does.
- layer8 4y ago
  I agree that not everyone has a knack for it. But I don’t think that’s the only factor. Software design/architecture is also hard and many devs aren‘t particularly good at it. We still recognize it as an important skill that requires education and training (and experience). If even just 20% or so of devs would get up to speed with how to write adequate documentation, and were enabled to invest the necessary time for it, that would already be a huge improvement.

tomcam 4y ago

> And in a Google doc, no less. That whole process sucks and I’m sorry you have to go through it. It’s probably the best solution of the time. My one question is… Isn’t that why we have github issues?

bentobean 4y ago
Because the pointy-haired bosses in product and all of the various managerial minions don’t have GitHub accounts, so it’s either that or (shudder) a Confluence page.
- tomcam 4y ago
  My condolences to you and yours.
- MathMonkeyMan 4y ago
  I think we work at the same company. Write your RFCs as markdown in a git repository. Stick it to the man!

coryrc 4y ago

"No" SWE ever got promoted for documenting someone else's code. Follow the incentives.

sublinear 4y ago
Huh? Documenting a terrible project is an excellent way to propose and volunteer yourself into a new project of your own design and ultimately get promoted into lead/architect/SME types of roles. I don't know anyone who has done it any other way.
- nullsense 4y ago
  Yeah I've done this too.

hnick 4y ago

This is why I also didn't particularly enjoy answering questions concisely at my previous company. I still did, I just hated it. Documentation can describe a system state, and how to use or approach it, but in my experience it really lacks in capturing the full depth of experience when it comes to interacting with it. All the little shortcuts and workarounds. All the debugging steps. Seeing something, and realising you've seen it before and solving it in 5 minutes instead of the entire day it took you last time. I could write a story about that day, but it wouldn't do anyone any good - they won't learn from that experience like I did and it won't spring to mind instantly. Assuming they even know where to find a piece written about their specific problem. So when someone says "How do I X?" all I can think about is all the incidental things I've learned when trying to do something else. This builds the bigger picture. I can answer your question, but you'll just paste the code in and be back to ask more tomorrow. I valued the coworkers who treated such things as more of a discussion and learning opportunity than a transactional question-answer routine.

perrygeo 4y ago
> the full depth of experience when it comes to interacting with it. This is the part that most people conveniently forget. Many people find it easier to create elaborate docs and processes than to regularly interact with the software system they've built.
deleted 4y ago
[deleted]
aorloff 4y ago
This is why effective documentation starts with run books.
- malandrew 4y ago
  I have a love-hate relationship with runbooks. I see them as tech debt for things you haven’t yet automated or made clear enough. If someone needs to go read a doc to understand what they need to do, you’re already behind.

GartzenDeHaes 4y ago

Management is about process, people, and resources. If you ask a manager to solve a problem, the solution will often be some combination of: - A defined and documented process - Project planning or organization changes - Staffing, purchasing, or contracting These are fine tools for a lot of business problems, but they are rarely helpful, and often harmful, for software development.

chii 4y ago

> outline every anticipated step along the way, all the tiny minutiae that you foresee yourself encountering and how you'll deal with it waterfall by any other name smells just as bad. I think the reason is that senior management has no trust in the developers, which is the ultimate cause of the need to have waterfall. Each reporting level wants to show concrete evidence that those under them are "doing their best", rather than to have trust that they are. Of course, it is understandable that people want concrete "evidence". But waterfall is the result, and you end up with big-bang designs, RFCs that are out of date because a change in circumstances necessitate a change that is not documented in an RFC. It is a management problem, not a software development problem, imho.

fexecve 4y ago

Most companies either do too little documentation (they have a little page with the bare minimum high-level overview), or they do way too much (detailed change request forms for every change, which go into a file cabinet, and are never looked at again). Alas, it's really hard to get people to understand that documentation is good and necessary when they've only ever been exposed to one or both of those systems.

deleted 4y ago

[deleted]

llamajams 4y ago

Y'all ain't work on projects with NO docs and no OG devs. I'll take an outdated Google doc over nothing and day of the week.