As the only person on my team who routinely documents my work (or at least who does so in a place visible to others), I definitely agree. I get very tired of people asking me things about my work where the reply is "it's in the docs, please check here: <link>." Makes me feel like a directory.
as someone who often would like to read documentation but have to end up asking the owner where it is like you describe
My problem is that there are too many pages that may or may not be relevant/and/or up-to-date, I want to know if there is a better way? I can't just read every document the company has on the topic in vain hopes for the answer. For example, I recently started working on my company's mobile app - noone has looked at it in a few months so its an ideal candidate for this kind of knowledge.
Despite that, I didn't go to confluence, because 99% of the stuff on there is half-finished drafts, and stuff aimed at our b2b customers, so I don't hold much hope in finding a solution to something which in principle ought to be very simple, like setting up my dev environment. In this case, the original project lead is no longer with the company, I had to ask a couple people who worked with it in the past, and it turns out they no longer knew how, and the documentation which had been written both didn't include it (it was customer-facing) and was also so out-of-date as to be irrelevant. I have no doubt that whatever developer made the app stopped writing documentation because they felt nobody would read it if they did! it's a self-reinforcing cycle.
I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.
There are two sides to the coin with not being able to find things - sometimes it is, as you say, because you are bad at searching for things, but sometimes things haven't been made in an easily searchable way. To name just three:
- sections with ambiguous names;
- multiple sections with the same name; or
- information is split across separate sections/pages.
Worst case is that there is detailed documentation but it's all in the comments of twenty different Jira tickets.
I do agree that user docs and dev docs should be separated though, as should specifications and development logs.
> I guess the only answer, as some others have mentioned, is a predictable organization system for the documentation, which crucially is actually taught to newcomers.
Precisely - just as you'd on-board new hires with information about codes of practise for development (code styles, nuances of internal git practice, etc.) you ought to at least have a "Contribution Guidelines" or similar doc that sets out how to structure and record information in the docs.
