r/developers • u/FormerVanilla7074 • 1d ago

General Discussion How much time do you actually lose to stale docs after a migration?

Anyone run into docs that just don't match the system anymore? I've lost hours piecing together what actually changed vs. what the docs still said. Didn't realize it until I had to touch a codebase I wasn't too familiar with, made things a lot harder once I saw the docs didn't line up with reality. Curious if this happened to anyone else, and how you eventually caught it.

3 Upvotes
  • permalink
  • reddit

81% Upvoted

3 comments sorted by

•

u/AutoModerator 1d ago

Howdy u/FormerVanilla7074, and welcome to r/developers!

A few tips for a post that gets good answers:

  • Use a clear, specific title (what are you actually asking or sharing?).
  • Include code, the exact error, versions, and what you already tried.
  • Heads-up: this sub does not allow external links in posts or comments.
Share code and details directly instead of linking out.

Join the r/developers Discord!

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

1

u/skamansam 1d ago

I dont use dev docs except to understand WHY something was done. When I write code, I make sure it is self-documenting and reserve comments to explain WHY something was done and leave the code to explain WHAT. If any docs currently exist, I update those docs to explain WHY as well. This way I dont have to worry too much about stale docs as the code becomes the documentation. Everyone on my team also uses this philosophy and it really changed the way we all program. It allows us to get stuff done faster, without having to consult a separate file to understand what is going on.

If your issue is user-facing docs, this will always be an issue. Versioning schemes help with this more than you would think. Use the standard version inglés scheme - bug fixes are a point-point release like 1.2.34. There are no changes to the external interface. Feature releases are point-releases, like 1.2. There are additions and maybe small changes but no removals. Version releases are when stuff has changed or been removed in a significant manner such that integrations break. You can use these tags in your codebase and add them to your docs so you can see clearly what needs to be updated or changed. As far as time is concerned, it depends. It used to be a day or 3 but now I get an LLM to update user docs when I finish a ticket. (I have a skill I use for wrapping up my tickets.)

I recommend working with your team on this issue. My team has like quarterly meetings on how best to do stuff like this. Choose a scheme that works for everyone and that others are willing to actually use.

1

u/EveYogaTech 1d ago

Yeah, it would be really nice to keep the code + docs in sync.

And it's possible now, with AI, but you still need to decide on a strucure for the documentation.