[al_borland]

The big issue, regardless of the platform, has been getting people to care about documentation. Those who are most qualified to write it, are usually the ones least likely to care about, because they don’t need it. I tried to buck this trend, as up-skilling others, in ways that didn’t require my constant time, seemed like a win. I tried to lead my example, but no one else ever joined in. I tried putting something together to formalize the process of reviews and got nothing but lazy rubber stamps, even from people who typically did excellent work. Getting people to care is the hardest part, in my experience. The bigger the organization, the worse this problems seems to get.

After seeing some people delete some big docs I wrote, which I think were still good, and changing documentation platforms so many times (usually to platforms with higher friction), my motivation to be a champion for good documentation has waned significantly. I still do write good readme files for my code, and end user docs for its use, but all the other little nice to have stuff I mostly just keep to myself in my own system. I’m sick of the changes, the friction, and people blindly deleting my work out of ignorance.

[freedomben]

I fully agree with your analysis here, but I would also add that documentation getting out of date is also a huge problem. Out-of-date documentation can be worse than no documentation at all when it is actively wrong. With the pace at which many software projects change, it can take almost no time at all for documentation to get out of date. Even just business processes often change quickly enough that information on the wiki becomes misleading.

Now that said, I have yet to actually use a platform with a good search functionality too. If stuff was easier to find, I strongly suspect that documentation would be better maintained, (provided that there is a cultural value around it)

[perrygeo]

> Out-of-date documentation can be worse than no documentation

One solution to this is to write structured and testable documentation. Easier said than done, but if your docs get regularly integration/e2e tested against reality, they stand a much better shot at staying up to date. I always recommend moving the docs as close to the development work as possible - ie docs get checked into git alongside the code and make sure tests fail if anything changes.

[NanaAmun]

Imo this just leads to out of date docs within the code it self. We have a no comment policy at the place I work for this reason.

[joshstrange]

What??? Like no code comments? That sounds insane to me.

I don’t want comments saying “adding 1 to X” but I DO want comments that tell me WHY we are “adding 1 to X”.

[breckenedge]

You’re not wrong, it is insane.

I’ve been told by a few developers over my career that “comments are a code smell”. I believe this is well intentioned but ultimately harmful advice.

[LtdJorge]

Documenting every piece of logic just because, I believe, is a code smell. However, look at Rust's documentation (or public crates, at varying levels), all the documentation is extracted from the code, with internal links and even external links between crates thanks to cargo doc (which I think is many times better than doxygen and what the Java and C# guys use, and let's not talk about the nonexistent alternative for JS/TS). Code examples in Rust docs can be made to reference the actual code in the crate, and the code block can be marked as "it compiles", "it doesn't compile", etc. And the compiler guarantees that's true. A block that doesn't compile is used as an example of incorrect code.

In the Unity game engine, they use docfx, and I heard from one developer that their system is done in a way that the code examples in the documentation import the actual code and the documentation fails a build if the code doesn't compile, similar to Rust.

[joshstrange]

Huh, I’d be interested to sit down with someone like that and better understand their viewpoint. I wonder if it’s just comments that describe what the code is doing (“what” not “why”) that they have a problem with and are just throwing the baby out with the bath water.

I’ve written mini-blog posts in comments before to explain a complex system or an odd bit of code that is the result of a massive bug in production that I want to document and explain the reasoning behind it.

[NanaAmun]

Exactly, If I can’t find 90% of the docs, chances are most other people can’t either, therefore no ones maintaining them.

[dataflow]

Get people to be rewarded for it and they'll immediately care, I think? It's hard to blame people for not caring about something that has no impact on their performance reviews.

[al_borland]

I was told by management they’d bake it into reviews to help drive adoption, but I don’t think they actually did.

[NanaAmun]

Sounds like we work at the same place.