4 ms·

> complaining about needing to do documentation The article's formulation: > You will be asked to write a 50-page documentation for some little code you wrote

by sshine 4y ago

> complaining about needing to do documentation The article's formulation: > You will be asked to write a 50-page documentation for some little code you wrote. The author does not complain just about writing documentation, but about writing an unproportionate amount of it that presumably isn't being read by anyone. I've seen that happen. People writing essays about software that are bound to get outdated and will never be read by anyone. In systems that are disconnected from the source code. > The writing is smug and shows no self awareness Maybe I share the author's disdain for the corporate setting, but I don't see the smugness. While the article may not acknowledge the cost and value of doing things slowly and bureaucratically, I fail to see how that is an expression of lack of self-awareness. It is mainly an expression of a preference for seeing direct change to business logic in a short amount of time, even for aging projects, because of direct ownership.

mytailorisrich 4y ago
> The author does not complain just about writing documentation, but about writing an unproportionate amount of it that presumably isn't being read by anyone. I've seen that happen. People writing essays about software that are bound to get outdated and will never be read by anyone. In systems that are disconnected from the source code. This has been the norm more often than not in most companies, especially larger ones. Hence the Agile Manifesto, written by people who've been there again and again.
- watwut 4y ago
  And still, working in company that does not document what the system does, it sux massively more. Because end result is that no one knows how to use our own software. You dont know what it is supposed to do, so it is impossible to keep that stuff working. It takes ridiculous amount of time to configure anything or reproduce bugs, because you need multiple calls to find the one person who barely remembers. Also agile manifesto is 20 years old. Agile is literally what most large dysfunctional companies do these days. It does not have no new solutions to actual real problems of companies, because it is old.
  - mytailorisrich 4y ago
    No-one ever suggested not to document! The comment I replied to says "inappropriate amount of documentation", the Agile Manifesto says "comprehensive documentation". That's the problem. Months, if not years, spent on pages after pages of comprehensive documentation that does not add any value and is obsolete by the time you start writing actual code. Lastly, the age of something is not a relevant criterion. Not much has actually changed over the last 20 years. What has changed is the explosion of web-related software, which is actually the best suited for the ideas behind the Agile Manifesto.
    - watwut 4y ago
      > That's the problem. Months, if not years, spent on pages after pages of comprehensive documentation that does not add any value and is obsolete by the time you start writing actual code. This picture is not any real company I ever worked in or real company I heard of from friends. Literally, not even before agile manifesto. > Not much has actually changed over the last 20 years. What has changed is the explosion of web-related software, which is actually the best suited for ideas behind Agile. That is not actually true, really. A lot did changed.
      - b112 4y ago
        This also glosses over something else. Comprehensive documentation can even be really well documented code! And in small corps, there's the "guy who wrote it" was "hit by a bus" scenario. It doesn't matter how dilligent, or how faithful someone may be when they leave, eg walking a replacement through the codebase can't happen of you're dead! This is how I document. I think about being hit by a bus, and what would this corp do? A replacement hiree do? See? Not doing this is, IMO, should be criminal. Like a CFO not keeping books.
onion2k 4y ago
People writing essays about software that are bound to get outdated and will never be read by anyone. I write a lot of documentation entirely with the awareness that no one else will read it. I write it for myself. I don't want to have to remember the intricacies of a system. I want to write things down, then move on immediately, and have the security of something I can refer back to if I need it when I revisit the system.
- turminal 4y ago
  But doing so is your personal preference, you (i hope) are not required to do so. Some people find it easier to organize their work differently or not at all. Some people are astonishingly productive despite not writing anything down, ever.
  - onion2k 4y ago
    But doing so is your personal preference, you (i hope) are not required to do so. I am required to in the sense that I define the policy about what gets documented on my team, and I said we write documentation about everything.
  - LeanderK 4y ago
    What if the teams changes? Intricacies must be documented despite that probably nobody will ever read it. Somebody might depend on it. Writing code is more about communicating how to solve a problem than just solving a problem, that's how I view it. If you don't communicate, nobody except you will ever understand it. It might be that you don't need to document a lot, maybe most is obvious if the key parts are sufficiently explained. But it's vital and sometimes it's better to write a bit more than a bit less. A thing is, outdated documentation might be worse than none, so it's a delicate balance.
    - wruza 4y ago
      What if the teams changes? Yeah, documentation will definitely help in this case. With it, you can swap teams and even companies, and it still works! This only fails in companies which do not review documentation and have no routine for keeping it in sync and testing it on e.g. newcomers, like you do for backups. Cause otherwise it is as good as never tested six months old backup.
oneeyedpigeon 4y ago
I've never seen anyone having to write a 50-page document just for "some little code", unless the author's definition of "some little code" is drastically different from mine. Without anything to back it up, that statement comes across as a huge exaggeration.

by sshine 4y ago

mytailorisrich 4y ago

> The author does not complain just about writing documentation, but about writing an unproportionate amount of it that presumably isn't being read by anyone. I've seen that happen. People writing essays about software that are bound to get outdated and will never be read by anyone. In systems that are disconnected from the source code. This has been the norm more often than not in most companies, especially larger ones. Hence the Agile Manifesto, written by people who've been there again and again.

watwut 4y ago
And still, working in company that does not document what the system does, it sux massively more. Because end result is that no one knows how to use our own software. You dont know what it is supposed to do, so it is impossible to keep that stuff working. It takes ridiculous amount of time to configure anything or reproduce bugs, because you need multiple calls to find the one person who barely remembers. Also agile manifesto is 20 years old. Agile is literally what most large dysfunctional companies do these days. It does not have no new solutions to actual real problems of companies, because it is old.
- mytailorisrich 4y ago
  No-one ever suggested not to document! The comment I replied to says "inappropriate amount of documentation", the Agile Manifesto says "comprehensive documentation". That's the problem. Months, if not years, spent on pages after pages of comprehensive documentation that does not add any value and is obsolete by the time you start writing actual code. Lastly, the age of something is not a relevant criterion. Not much has actually changed over the last 20 years. What has changed is the explosion of web-related software, which is actually the best suited for the ideas behind the Agile Manifesto.
  - watwut 4y ago
    > That's the problem. Months, if not years, spent on pages after pages of comprehensive documentation that does not add any value and is obsolete by the time you start writing actual code. This picture is not any real company I ever worked in or real company I heard of from friends. Literally, not even before agile manifesto. > Not much has actually changed over the last 20 years. What has changed is the explosion of web-related software, which is actually the best suited for ideas behind Agile. That is not actually true, really. A lot did changed.
    - b112 4y ago
      This also glosses over something else. Comprehensive documentation can even be really well documented code! And in small corps, there's the "guy who wrote it" was "hit by a bus" scenario. It doesn't matter how dilligent, or how faithful someone may be when they leave, eg walking a replacement through the codebase can't happen of you're dead! This is how I document. I think about being hit by a bus, and what would this corp do? A replacement hiree do? See? Not doing this is, IMO, should be criminal. Like a CFO not keeping books.

onion2k 4y ago

People writing essays about software that are bound to get outdated and will never be read by anyone. I write a lot of documentation entirely with the awareness that no one else will read it. I write it for myself. I don't want to have to remember the intricacies of a system. I want to write things down, then move on immediately, and have the security of something I can refer back to if I need it when I revisit the system.

turminal 4y ago
But doing so is your personal preference, you (i hope) are not required to do so. Some people find it easier to organize their work differently or not at all. Some people are astonishingly productive despite not writing anything down, ever.
- onion2k 4y ago
  But doing so is your personal preference, you (i hope) are not required to do so. I am required to in the sense that I define the policy about what gets documented on my team, and I said we write documentation about everything.
- LeanderK 4y ago
  What if the teams changes? Intricacies must be documented despite that probably nobody will ever read it. Somebody might depend on it. Writing code is more about communicating how to solve a problem than just solving a problem, that's how I view it. If you don't communicate, nobody except you will ever understand it. It might be that you don't need to document a lot, maybe most is obvious if the key parts are sufficiently explained. But it's vital and sometimes it's better to write a bit more than a bit less. A thing is, outdated documentation might be worse than none, so it's a delicate balance.
  - wruza 4y ago
    What if the teams changes? Yeah, documentation will definitely help in this case. With it, you can swap teams and even companies, and it still works! This only fails in companies which do not review documentation and have no routine for keeping it in sync and testing it on e.g. newcomers, like you do for backups. Cause otherwise it is as good as never tested six months old backup.

oneeyedpigeon 4y ago

I've never seen anyone having to write a 50-page document just for "some little code", unless the author's definition of "some little code" is drastically different from mine. Without anything to back it up, that statement comes across as a huge exaggeration.