3 ms·
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 l
by al_borland 1y ago
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.
- dataflow 1y agoGet 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 1y agoI was told by management they’d bake it into reviews to help drive adoption, but I don’t think they actually did.
- NanaAmun 1y agoSounds like we work at the same place.
- freedomben 1y agoI 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)
- NanaAmun 1y agoExactly, If I can’t find 90% of the docs, chances are most other people can’t either, therefore no ones maintaining them.
- deleted 1y ago[deleted]
- perrygeo 1y ago> 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 1y agoImo 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 1y agoWhat??? 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 1y agoYou’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.
- 1y ago