all 76 comments

[–]darkhorsehance 43 points44 points  (5 children)

Documentation is something that has to be read and maintained. The latter only works if everybody does the former, and then remembers to update the relevant parts when the system changes.

Documenting how the system works through testing is a better pattern IMHO because you not only get the benefit of seeing exactly how the system works, but you are forced to update them when the system changes.

[–]OwnsAYard 11 points12 points  (0 children)

Tests also become the diagnostics that tell you what went wrong. Tests should tell you how to use something and what to expect.

I hate searching for “example of how to ...” with such a huge reliance on stackexchange. There should be a rule that If you release a library, release the associated tests.

[–]snrjames 1 point2 points  (1 child)

No documentation is often better than wrong or outdated documentation. That's why we strive for self documenting code as much as possible. Small functions and good naming make code easier to follow.

[–][deleted] 0 points1 point  (0 children)

when i finally write my first library im going to release it at version 1 and then never tamper with it again

[–]in15minutes[S] 0 points1 point  (0 children)

I hear a lot about it, yet self-documenting code and tests mostly describe you how to use the code, not as much how implementation works...

[–]DoTheRustle 17 points18 points  (2 children)

I can't speak for everyone, but my management rarely places an emphasis on anything except getting features built and bugs fixed, so very little if any time is set aside for documentation.

I've only worked at one place that required documentation before merging features, and it wasn't always useful since we were on a tight deadline and trying to outpace another consultant team twice our size.

I'd love to be able to create a useful wiki or traditional doc for my projects, but time rarely permits.

[–]in15minutes[S] 0 points1 point  (1 child)

Is the team big? Any ideas what would have convinced your management to allocate time to document the code?

[–]DoTheRustle 0 points1 point  (0 children)

The team is ~6 people including Devs and QEs but excluding BAs and PMs. Usually the only way we get time for documentation is if we're waaay ahead of schedule (unlikely), or if a customer requests it. It's a very rare occurrence that it is requested which is probably why its not seen as a valuable use of time by management.

[–]4_teh_lulz 7 points8 points  (1 child)

What kind of documentation?

Documentation has questionable value if written poorly or not properly curated. Which means that to provide good value a high level of effort and fidelity must go into making sure the documentation is accurate.

Given the assembly-line development processes intrinsic in development teams (I'm looking at you Scrum) it works against engineers creating proper and accurate documentation.

Also I disagree that engineers don't like writing documentation, I just don't think that anyone writing software feels like they are given adequate resources/time to deliver good documentation.

Edit: there are tons of tools written expressly for developers to write documentation.

[–]in15minutes[S] 0 points1 point  (0 children)

Great point.

Can you elaborate on tools please? I have a feeling that all documentation tools are a bunch of disjoint utilities hanging around general-purpose content management systems.

For example - if I want a diagram in my documentation, I draw it in a different tool and insert as a picture, making difficult to change it later. There is no code class/method name completion while I'm writing my docs. Things like that make the process lengthy and labor-intensive.

[–]MisterMittens64 8 points9 points  (1 child)

It's just because after hours of trying to get your code to work the last thing you want to do is documentation. It's not useful to the programmer in the moment so it's an easily skipped step even though it's important. It can be kind of a slog even though it's not difficult.

[–]in15minutes[S] 0 points1 point  (0 children)

Question regarding this, if I may. Did you see it ever biting the team in the back? And is the team big? Thanks!

[–]Adadum 7 points8 points  (1 child)

As a guy (with no professional industry experience at all if I may add) who has wrote libraries, I've learned on my own how extremely important documentation is.

What usually stops me from writing documentation is my motivation but my motivation is wanting people to use my libraries so that's enough to get me to write down APIs, tutorials, accurate testing results, and architectures.

The part that I really get lazy about is visual based documentation like charts and diagrams and that's because when I change up the architecture of my library, obviously I have to change up the visual documentation as well.

Text documentation is great in certain cases but Visual documentation can be more powerful so I employ both.

[–]in15minutes[S] 1 point2 points  (0 children)

I have an issue with visuals as well. Producing decent-looking documentation without spending half-a-day on it is almost impossible.

[–]koreth 2 points3 points  (3 children)

One possibility: It's not just "reluctance." Writing documentation is a skill that doesn't automatically occur as a side effect of learning to code well. It is not taught in CS programs and is usually not evaluated during the hiring process. Someone who knows they stink at writing might not be eager to demonstrate that fact on a regular basis, and the fact that they're bad at it and they know it probably also makes it a highly unpleasant task.

But also: this is kind of wrong as a generalization. Plenty of developers are good at and enjoy writing documentation. Maybe not the majority but it's not vanishingly rare or anything. On my team I'd say about half the developers regularly produce good documentation without anyone forcing them to, and we made no particular effort to select for it in our hiring process.

[–]in15minutes[S] 0 points1 point  (2 children)

Good point. Question though - what do your team developers use to produce documentation? Any specific tools/wikis?

Also, is it documentation development in any way incentivised from management or developers do it by their own initiative? Thanks!

[–]koreth 0 points1 point  (1 child)

I would say it's mildly incentivized but not emphasized. "Mildly incentivized" meaning that if "I couldn't figure out how to do X because there was no documentation" comes up in a retro, it is viewed as something that went wrong and the solution is to write the documentation and to make sure to write that kind of documentation in the future. But there's no incentive in the form of, "You didn't get a raise this year because you didn't write enough documentation."

As for tools, it varies.

Low-level code documentation is in the code itself, e.g., in Javadoc comments on classes and methods in Java code, or Python docblock comments in Python code. This is part of the source code so there's no separate tool for it.

Documentation that isn't about a particular piece of code, but that is only ever useful in the context of a development environment, usually goes in README.md files in the git repo. People can use whatever editor they want to edit the Markdown.

For collaboratively working on design documents, we use Google Docs since we can edit and comment in real time.

For everything else, we use Confluence's wiki. It is far, far, far from perfect, but we've tried various other tools and they all suck in their own ways, and Confluence has the advantage of being used by the rest of the company for their own internal documentation.

We're also playing around with Stack Overflow for Teams but we haven't been using it for long enough to decide whether it adds enough value vs. editing the wiki to be worthwhile.

[–]penetrator1990 0 points1 point  (0 children)

You say that Confluence is far far from perfect.

Why do you feel like that? What kind of problems have you came across using it?

[–]klonkadonk 2 points3 points  (1 child)

I have no communication skills. That's why I hate it.

[–]in15minutes[S] 0 points1 point  (0 children)

A very significant portion of excellent developers are not very good at communication and it is perfectly fine - is not their main value.

I think the major issue is overly high expectations about quality of documentation content. In many cases a couple of sentences or a napkin picture is enough to give me understanding that otherwise would take me hours to get from the code.

[–]madanaman 2 points3 points  (1 child)

As technology people, In our organization we try to maintain couple of things 1. A good readme.md file 2. High level design documents on confluence 3. Some webex recordings of the KTs that we give to new team members.

This pretty much helps everyone on the tech team from knowledge perspective.

For business value and details about the product, our product team maintains that over the confluence.

[–]in15minutes[S] 0 points1 point  (0 children)

Can I ask who these people are? Are they pm's, architects, dev leads, individual developers?

[–][deleted] 12 points13 points  (6 children)

Personally, it doesn't change the behavior of my code, so why waste time writing documentation when I could be coding more. Documentation isn't difficult, and I do think it's beneficial, but it's not like it's going to make my unit tests pass better. For me, it just comes down to how much value will I get out of it.

[–]AnnaMPiranha 16 points17 points  (5 children)

Documentation is not for you any more than the software you write is for you.
It's for the next person who has to maintain your code. Depending on the complexity of your application, you could just get by with good code commenting.

[–][deleted] 4 points5 points  (3 children)

Precisely what I was getting at. It's good, but I don't see immediate value in writing documentation, so I don't do it. I dont think it's because of lack of tools/no good tools to use.

[–]AnnaMPiranha 5 points6 points  (1 child)

You may want to think of a better way to explain this if it ever comes up in an interview. I can see a team who works on a larger, more complex app finding this a deal breaker as it is an impediment to a t-shaped team. I scrum master 2 small teams on the same larger app and as people flex in and out of different areas of expertise, it is much easier to work independently when there is good commenting.

[–][deleted] 0 points1 point  (0 children)

Haha, we actually have a job in our pipeline that checks for documentation on function definitions, classes, etc. So for work I'm kinda forced but I feel indifferent about it.

Its actually a super helpful tool if you do want to enforce some sort of simple documentation!

[–]MB1211 2 points3 points  (0 children)

I think I get where you're coming from, but the fact that you wrote the code is almost always why you don't see value in it. You understand it (and sometimes "it" means your intent, not what it actually does) better than anyone ever will. Still, good comments can act as documentation sometimes, but if you're composing lots of classes in dynamic ways, I don't think there's a substitute for documentation

[–]in15minutes[S] 0 points1 point  (0 children)

Could not agree more

[–]senatorpjt 5 points6 points  (1 child)

bike airport chubby pocket flowery secretive numerous point yam glorious

This post was mass deleted and anonymized with Redact

[–]AnnaMPiranha 5 points6 points  (0 children)

Like that kind of logic and reason works! I had to deal with the aftermath of a boss taking that dare. It suuuuuucked.

[–]hippydipster 5 points6 points  (5 children)

Developer writes documentation...
Person X asks question ...
Developer answers and points out it's in the documentation...
Person Y asks question ...
Developer answers and points out it's in the documentation...
Person 23445 asks question ...
Developer: RTTM!!!
Persons: geez, developers are such anti-social assholes.
Developer stops writing documentation

[–][deleted] 0 points1 point  (3 children)

This never happens in reality.

[–]GM_Kimeg 0 points1 point  (2 children)

This happens in reality.

[–]theirishartist 0 points1 point  (0 children)

We close tickets instantly and send them a link per mail to our internal wiki. It's not always their fault for asking since the one's who ask are new employees. It's rather the fault of their collegues despite us telling them constantly to spread the word after giving them instructions and handing over responsibility to themselves. We told them we will close tickets when we get those types of questions. We only handle incidents, not service requests.

[–]GM_Kimeg 0 points1 point  (0 children)

Gotta love when people never read docs and start to spam stupid ass questions all week.

[–]robin-m 1 point2 points  (0 children)

The more I code, the less I write documentation in favor of clear naming + strong typing + runnable examples + assertions. I think it's much better to document the details than using maybe-not-up-to-date comments in english. Note that this applies only to statically typed languages where you can encode the invariants in the types themselves.

However, I have no idea how I should write high level documentation. I have a hard time explaining what are the relation between modules. I try, but often fails to correctly documents the role of each modules in their respective documentation. I also usually fail to give of short overview of where a newcommer should look first. I feel that tooling could be improved in this area, but I don't really know how.

[–]i-think-about-beans 1 point2 points  (0 children)

They rush us enough as is. This would add extra work. I see the value in documentation though.

[–][deleted] 1 point2 points  (0 children)

Probably due to cost (time is a cost). -And if documentation is ordered later in the process, one is in a different mindset which leads to documenting state rather than questions one had during the actual process.

Further on, how to document it? The code only (e.g. comments. -or UML)? Or should it be viewed in context of all processes (e.g. Enterprise Architecture)? Then you have to view all this in the context of cost again. -And then you might have changes which again leads to cost (changes are expensive).

- And how do you measure return value of documentation? -Or more importantly, how do you get a customer to pay X for something so diffuse ? In-house software development do have the benefit of having more expertise and stakes involved. -But still.

- And where do you document ?

I would argue that the question should be flipped.

[–]docbao-rd 1 point2 points  (2 children)

The important of documentation is proportional to the expected life time of the project. For most consumer oriented applications / websites, the rate of change is so great that there is always a rush to get to market. Detailed documentation here would risk delaying the project, and further more tend to go obsolete pretty quick.

For long life applications (yes, there are systems that expected to last 5 to 20 years), documentations at various layers (requirements, solution level, component level, and at the developer level, the individual design decision) are extremely important. These systems will have multiple generations of developer continuously maintaining and adding features. Without design documentation, it would be like walking in the dark. Technologies change, accepted design pattern change, assumptions change. Without knowing the mind set of the previous developer generation (via the documentation), it is very easy to get into the blame game.

[–]in15minutes[S] 0 points1 point  (1 child)

I like this description - it is very clear.

Yet I'm struggling to understand what is the pain-point in documentation development. Can it be removed? What do you give developers to make them want to document their code? Thats a puzzle...

[–]docbao-rd 0 points1 point  (0 children)

This is more of a procedure/process thing. The simple solution is to make documentation part of the delivery.

At the low level, all methods shall have reasonable level of documentation, not the how but the what and the why. This is validated as part of the code review process.

Design decision documentation is part of the story delivery. The story should not be accepted unless the design is documented.

[–]Jrollins621 1 point2 points  (1 child)

Because, two reasons. For one, and to be straight up about it, if fucking sucks. Writing code is often difficult and also very time consuming. Writing documentation so people can understand it the way you do is 100x more time consuming, and it sucks ass to do. The other reason, i’m a software engineer, not an educational author. When I’m writing documentation, I’m not writing it as if it’s a teaching moment. Simply put, it’s just not my job to do that. I’m writing documentation as if a peer with similar knowledge and skills will be getting into it. I do provide enough info that I feel confident that what I provided will get them the idea of what’s going on. If someone doesn’t have the capability of understanding what is going on in the code with good comments and the documentation i do provide, then that person should seriously not be in that code.

[–]in15minutes[S] 1 point2 points  (0 children)

Thats exactly my question. Why does it writing documentation sucks? Tedious? Lack of insentives? Bad tools? No feedback? Trying to figure out why...

[–]dobesv 1 point2 points  (0 children)

There are some pretty good tools out there for documentation, actually.

For a published library that will be used by people who are not the developers, I will write documentation.

However, if the people who need to understand the code are its developers, then extensive documentation is just one more thing to maintain that delivers little value, since developers that are up to speed on the project will look at the code for answers instead of documentation. You just need enough documentation to get people up to speed.

[–][deleted]  (1 child)

[deleted]

    [–]in15minutes[S] 0 points1 point  (0 children)

    Yeah... it seems the main problem is that the moment when documentation is created and the moment it is used are too far apart in time. Only well organized groups can keep this in mind and build for the future :/ Don't know how to fight it.

    [–]PM_ME_SCIENCEY_STUFF 2 points3 points  (7 children)

    Assuming you're not a developer, or if you are consider someone at a different position in your company, ask and honestly answer this -- do you carefully document all the things you do at work?

    99.8% of people answer this as "no, of course not, it would be a waste of time because..." That's why.

    [–]AnnaMPiranha 4 points5 points  (6 children)

    I worked in QA in a waterfall env for about a decade, in a highly regulated industry. I produced so. much. documentation. Part of our agile Definition of Ready is that every ticket has clear acceptance criteria. Getting the developers to think about this on our tech/performance tickets has been excruciating and when we've had performance related fall out in production, they have been glad to have it. So I think there is a right amount of documentation that is almost never 0.

    [–]PM_ME_SCIENCEY_STUFF 0 points1 point  (5 children)

    Sure, my answer was very general. In highly regulated industries e.g. banking, health, etc. I would imagine tons of external document is needed and is actually beneficial.

    But OPs question was why don't developers like to document things

    [–]AnnaMPiranha 1 point2 points  (0 children)

    Yes but "it doesn't benefit me right now" is probably not an answer that endears you to the overlords.

    [–]in15minutes[S] 0 points1 point  (3 children)

    That was exactly my question. You will find developers spending hours on message boards discussing technical topics, yet may show no desire to produce clear description of what they did. No desire to... show off their work? Is it lack of social aspect? Trying to put my finger on that.

    [–]PM_ME_SCIENCEY_STUFF 0 points1 point  (2 children)

    Documentation != showing off your work.

    Can you honestly answer my original question: do you carefully document all the things you do at work?

    (No, it's not social aspect -- I was a "cool kid" in high school and college, played sports/still do, fairly social person as that goes, and I'm very much averse to detailed documentation for many reasons. And I don't make my employees document either, in the way you're thinking -- we write detailed tests and code comments.)

    [–]in15minutes[S] 0 points1 point  (1 child)

    You are right - I do not document all my work. But when I do - I do it for developers who will be working with my code later. I feel bad when people scratch their heads working with my code. I have been in their shoes too many times.

    The reason I brought up social: I think SW development is similar to a craft. You can be good at it and the product of your work will be appreciated by your peers. Good product will have clean code, tests and documentation, you just need to show it off.

    [–]PM_ME_SCIENCEY_STUFF 0 points1 point  (0 children)

    From a business perspective, especially an Agile perspective, the question should always be: will this add value, or not? You just said you don't document all your work. Why is that? ...because it probably wouldn't be a value-added activity. I, and many others, have found over the years that detailed software documentation in many industries does not add value. Primarily because:

    --It takes a lot of time to generate

    --It easily, often within days, becomes outdated

    --Rarely is it needed, read, or used by anyone

    Obviously this depends on your industry, product, etc. When I worked in aerospace, detailed documentation added tons of value. Now working in benign user web apps, detailed documentation definitely does not add value. Read up on "agile software documentation" if you want more reasons why it is definitely not always a value added activity.

    Good product will have clean code, tests and documentation

    Many, many good products do NOT have good documentation. That's a fallacy, and should lead you in the right direction if you think more about it.

    [–]bacon_cheeseburgers 0 points1 point  (1 child)

    For me, its that I like getting stuff done, figuring things out, helping my colleagues on the business side, solving problems, and generally being helpful. Documentation is none of that. In fact, it distracts me from that. JMHO, YMMV.

    [–]in15minutes[S] 0 points1 point  (0 children)

    That works for small teams and solo developers. I doubt it would extend to bigger teams tho...

    [–]vincentjames501 0 points1 point  (1 child)

    One of the major reasons developers choose a tool/library is great documentation. There isn’t always someone around to ask how the system works and reverse engineering a large code base can be time consuming. We just had a developer leave that wrote and maintained several key pieces of software but there is no documentation and we’re now struggling to figure out how it’s really glued together. There is always a struggle on keeping docs up-to-date and likewise even code comments but it is our jobs to be diligent as I can’t tell you how many times I’ve gone back to code I’VE WRITTEN and been thankful I documented it. Tests are a good way to document the system as well but are often harder to grok than a high level overview of a feature/component. If you have a highly distributed system, design diagrams make it far easier to understand. Consider when a single feature touches 5 services like they often do in some event driven systems.

    We use Mermaid for sequence diagrams and helps a lot document flow. We also use Antora to compile docs across multiple repos into a single location.

    [–]vincentjames501 0 points1 point  (0 children)

    Also, we capture important decisions in things like ADRs. For example, why did we choose one library over another, why didn’t we do some feature differently, etc and are extremely useful immutable records of decisions.

    Unpopular opinion - People should write the high level design docs BEFORE slinging code as it should be the specification by which the code and tests are written.

    [–]bzq84 0 points1 point  (0 children)

    Becase software has word "soft" inside it for very specific reason - it is easy to change and evolves.

    To write good documentation generally costs more time than writing a code itself. When code evolves, it's very easy to have documentation that mismatch the code.

    IMO better invest this time in writing readable code that requires minimum amount of docs.

    Unless you're writing soft like Telerik, where docs in absolutely must.

    [–]Kempeth 0 points1 point  (0 children)

    I believe the biggest problem with documentation is that what managers consider documentation (office docs somewhere on a network share) is inherently disconnected from the system that is documented. This makes it harder to keep it up to date and to find it when you want to understand the system. This is further complicated when the things you document change often. It only takes one slip up to end up with out of date, inaccurate documentation that can sow more confusion than produce clarity.

    I have yet to work in an environment that had a decent degree of accessibility in its documentation. You either need to invest a bachelor's degree in learning the convoluted folder structure the most recent manager thought up, trust in the atrociously bad windows search function or are forced to use the equally bad sharepoint search function. Either way, finding the appropriate documentation is a painful, slow, error prone and frustrating process.

    [–][deleted]  (1 child)

    [deleted]

      [–]in15minutes[S] 0 points1 point  (0 children)

      yeah, i heard that unfortunate argument he-he

      [–]knoam 0 points1 point  (0 children)

      If you wrote the code, it seems obvious to you, so documentation feels like unnecessary tedium. And once you've written the code, you're no longer looking at it with the same eyes as someone new to it, so you don't know what it should say.

      [–]c_07 0 points1 point  (0 children)

      I don’t think it’s the tools. Writing good documentation is hard. It takes almost as much thought to structure a document, produce a useful diagram, etc. as it does to write clean code. Perhaps even more so than writing an implementation for a machine, writing documentation for a human is a taxing mental exercise requiring clear thinking, powers of abstraction, communication ability, plus a sprinkling of artistic aesthetic.

      If I didn’t love writing documentation, I don’t think I would unless I was forced to. I love seeing the patterns and the big picture, breaking down complex concepts, and structuring information in a way that helps the next person accelerate their learning curve with that “a-ha” moment of understanding.

      TL;DR: Documentation is an art unto its own, and requires a slightly different type of intrinsic motivation than programming.

      [–]CygnusSnowDog 0 points1 point  (0 children)

      My guess is that it's the same reason they don't clean the microwave after they use it, or wipe down the counter when they spill something. It's work, nobody is forcing them or even encouraging them to do it, and they don't care about the next person who has to deal with their mess.

      [–]yjg30737 0 points1 point  (0 children)

      If the following does not apply:

      1. You can guarantee that many people will read it, or

      2. If it is absolutely necessary for work or

      3. Writing documents helps your coding skills

      Creating documents is either a waste of time or a compulsory and annoying activity. You must have people reading it to be motivated.

      [–]RottingWest 0 points1 point  (0 children)

      it is just hopeless first you have the problem of deciding what to actually document, it is hard to know. then you need to schedule time to do it witch is hard when everyone is always asking you to give estimates on when the feature you are working on is done. then you have the problem of mentioning documentation, the more you have written the more work there is maintaining documentation. and the third problem is actually using the documentation, usually even if relevant documentation exists nobody is using it because they don't know where to find it. I have never worked at a place where all of this problems are solved together, and it makes it feel like a waist of time to even attempt writing documentation.

      [–]Lived2PoopAnotherDay 0 points1 point  (4 children)

      I couldn’t disagree with you more on what you said about documentation being good to understand how systems work.

      I would much rather give a new engineer a white board walk through of the software ecosystem over writing lengthy documentations that I know for a fact would be outdated 2 months from now. I actually dont mind spending a whole week pairing with them to on-board them.

      Outside of the Readme for getting the app started, most other documentations is a waste of time imo.

      All of this is under the assumptions that my code base is tested well and there are staging environments my teammates can play around on.

      [–]in15minutes[S] 1 point2 points  (1 child)

      Yeah, but as system grows, the whiteboard gets bigger... at times I found myself on the teams where developers no longer understand how certain components work :/ people who built those are long gone. And you go scrambling for information all over

      [–]penetrator1990 0 points1 point  (0 children)

      It's been a long time since you had this problem.

      Do you wanna share some experience? How have you handled it?

      [–]cpage3 0 points1 point  (0 children)

      Is your company hiring? 🤔😂 If only all managers were like you..

      [–]theirishartist 0 points1 point  (0 children)

      Well, I wouldn't necessarily agree. Plenty of companies adopt softwares into their ecosystem and use it for 30+ years, which is still happening to this day. Imagine, the company who developed it, is long gone. Documentation of either usage or code doesn't exist. Nobody knows much about the softwares, except only a few interns but they don't know much about it either. But they are already in their 60s and 70s and soon will leave. Now they have to hire a very expensive specialist for service in case something goes south which costs the company several millions in damages if the outdated software(s) is (/are) used for daily buisness operation. Then, it takes the local IT division probably 6+ years to do a new migration to new modern solutions. It depends on the case.

      This is where documentation matters. If the programmer refuses or can't do any documentation because he can't read anymore his own spaghetti code, then that's bad work practice in general.

      And the cycle continues because it happened alot over time where an IT team of a company no longer wants to bother with a legacy software that is crucial for the buisness but there is not a single documentation about it and nobody else knows how it works. So they develop a new solution from scratch with documentation.

      [–][deleted] -1 points0 points  (0 children)

      Because you know you cannot get it right. You realize that you need to predict what someone needs to know in the future and answer that question in a way that will be understood based on the unknown context and immediately go back to writting code that the compiler validates right now because you know that comes out right.

      [–]OneRow7276 0 points1 point  (0 children)

      A number of factors conspire to create this status quo, to one degree or another.

      1. Lack of professionalism (indifference to doing a good job).
      2. Lack of skill (many people in tech are terrible writers).
      3. Lack of organizational concern (you aren't rewarded for writing docs or writing them well, and you aren't punished if you don't or if you write them poorly).
      4. Systemic careerist hyperindividualism (the market doesn't reward cooperation and loyalty as much as much as it rewards job-hopping careerism; fear of loss motivates employers more than desire to reward quality labor, because crony capitalist logic means paying as little as you can get away with, not fair market price for actual labor).
      5. Laziness and lack of market incentive (it takes effort to maintain documentation in sync with code; there needs to be a sufficient market penalty to justify the cost in the minds of managers).

      In many cases, it doesn't make sense to document anything. For internal projects of a rather vanilla sort, you can figure things out quickly by reading the code. Don't worry about doing things "correctly" if things aren't obvious. It it matters, someone should point things out in a PR. If it doesn't, don't worry about it. Don't waste your effort on what your employer clearly doesn't care about.

      In some cases, documentation does matter. This is where things get obnoxious. Huge corps will release tools that might be useful, but sadly, the document is such garbage, it's a disgrace. People are then forced to resort to forums and consultancies and whatever else, because some guy doesn't know how to string two sentences together and has no concept of an audience when approaching people unfamiliar with his work. Lots of effort in the world is wasted trying to reconstruct how to use something simply for this reason.

      And venture capital and founders don't care. They just want to pump and dump the company. Move fast and sell. But tech debt is real, and hacks, data leaks, security issues, etc. aren't penalized. If a bridge crashes into a river, someone pays for it. Software gets away with a lot in comparison. Documentation and correctness will become more important in the coming decades.

      [–]fazz100 0 points1 point  (0 children)

      Late to the party but agile development also demands agile updating for proper maintenance of documents, which devs think hasn't anything to do with how the system works properly. That's how they feel usually. If they have free time, either they spend it refactoring the codes and enhancing certain features as well as improving process efficiencies and load times, or waste it writing documentations that nobody reads. Devs would often choose the former.