loading...

Discussion on: What makes maintaining documentation difficult?

Collapse
rmarpozo profile image
Rubén Martín Pozo

From my experience, documentation tends to get old and outdated pretty quickly and that's, in my opinion, the main problem. When you can't trust your documentation it loses all its value.

We're currently using Guru. It allows us to write small doc snippets (mitigate laziness) and keep them up to date since Guru will notified the authors when the snippet is getting old to check if it's still valid and fresh.

You can also create these snippets from Slack. Most of the time a discussion starts in Slack and at some point someone adds a guru snippet to wrap it up.

Collapse
cjbrooks12 profile image
Casey Brooks Author

That's an interesting tool, I've never heard of it before. I like the idea of incorporating documentation as part of the normal daily discussion, and having a bot checking for potentially out-of-date documentation. Do you find this resource to be sufficient for most of the new developers on your team?

Collapse
rmarpozo profile image
Rubén Martín Pozo

Sure, it's replaced our documentation wiki altogether. People really like it and it's full of useful information. I think it certainly is worth the cost. We have a board for newbies with a lot of "cards" with useful information. Things like, how to start building a service, how to setup IDE, how to connect to different places, how our CI works and so on.

Thread Thread
pdanny profile image
pdanny

That's true, many of the conversations where devs are looking for a specific piece of knowledge originate in Slack. There are also other tools such as Obie, etc also integrate with Github to help close the loop.