As a DevOps engineer, I'm facing a common challenge: we have documentation, but it's often hard to find. Typically, only a couple of senior team members know where everything is stored, which can be an issue if they're unavailable. I'm currently using Confluence and want to ensure that documentation is easily accessible when it's needed. I'm exploring ways to make this explicit, rather than rely on team members to direct others to the right resources. Here are a few strategies I'm considering: attaching relevant documents to Jira tickets, creating 'Hook Pages' that pose common questions like 'How do I do X?' with links to the respective guides, and having guides for multiple queries. How do you approach making documentation easy to find?
8 Answers
I prefer my code to be self-documenting. Instead of separating documentation, I generate API documentation and aim for readability through descriptive naming conventions. If everything is straightforward, you won’t need extensive docs. Using mono repositories simplifies everything, too.
If you're working with Confluence, don't forget to leverage the labeling system. It boosts page discovery in search results. Also, using the status tool at the top of each page can help keep your docs relevant by indicating their last updated status.
If someone asks me something that's already documented, I usually respond with a Google search link tailored for them. It's like a gentle nudge towards the resources they need. If I'm feeling nice, I might throw in a direct link to the specific documentation.
Haha, classic! It’s a good way to guide them without doing the work for them!
We utilize RAGs (Red, Amber, Green) specifically to address this issue—although I wonder how effective that method is in keeping things updated in 2023.
How do you ensure the information in your RAG remains accurate? Outdated documentation can lead to misinformation.
We developed our own documentation portal with a focus on contextual searches. The search options on Confluence can be pretty lacking, so we made sure to create a visually appealing interface where users can customize their experience. We even included mini-games to encourage engagement! It’s an entire ecosystem that enhances documentation management and searchability.
Wow, that sounds awesome! Custom themes and games? Now that's a way to get people to read docs!
I've found that a combination of centralized and distributed documentation works best. Each repository should maintain its own docs but link everything from a central source where updates can be made easily—think wiki-style. This helps ensure proper access and quick updates, plus you can even attach files that aren’t necessarily linkable directly.
That's exactly what we do! Someone asks about docs in a Teams post, and someone else unrelated to that code can share a link almost immediately. We also publish Markdown from our project repos to our knowledge base automatically via CI/CD, which is super efficient.
Having a centralized documentation hub really takes care of this issue. As long as it has robust search functionality, finding information becomes straightforward.
Exactly! Confluence has its flaws, but it can still be effective.
Totally agree. I wish we could apply the same approach to processes like deployments without needing extra documentation!