4 ms·
Not Backstage specifically but I think you're describing documentation generally in a company of any size. Some tools are better (e.g. better search) than other
by ghaff 4y ago
Not Backstage specifically but I think you're describing documentation generally in a company of any size. Some tools are better (e.g. better search) than others. But documentation is something that's (hopefully mostly) correct the day it's created and tends to get less correct over time and may or may not get updated or formally deprecated.
There needs to be a process and probably at least a librarian and even then it's often not obvious. In my experience, a lot of written material gets into the "not quite right any longer but we don't have anything better"--and if you go to update it there's invariably a lot of things that end up getting changed. Not sure I've ever cracked open an old paper or blog post and just changed one thing.
- vxNsr 4y agoYup, in any midsized+ org you need a librarian if you want your doc/kb to be kept in good shape, that person also needs to have a lot of soft power/people skills to enforce rules and procedures many might feel are secondary to their main responsibilities.
- BrandoElFollito 4y agoI had an idea some years ago to gradually lower the contrast on the doc page until the users get frustrated and raise concerns/tickets/escalations. bringing it to a normal contrast again requires a review of the documentation and some kind of punishing if someone just clicks "yeah, it is still fine". I hate outdated documentation, primarily including mine.
- mgkimsal 4y agoNot sure you'd necessarily need to rely on contrast (or... contrast alone - reader mode and similar might render that not noticeable for folks). Some datestamp next to multiple areas with a "last reviewed/approved on" info would likely be useful, esp if someone could flag items that are known out of date/wrong/broken for review, even if they didn't know what 'correct' was. I've hit this multiple times as a new person on a team/project - at least those that had moderate documentation. I know "example A" doesn't work, but I don't yet know why it's wrong or how to fix it, but flagging it for review would help me not lose track of it.
- yjftsjthsd-h 4y agoI have seen personal blogs where any post that's older than some threshold automatically gets a banner tacked on the top that says something to the effect of "hey, this is an old post, things might have changed since then". Adding something like that to a Wiki seems like a reasonable idea.
- mgkimsal 4y agoGoing further, having someone - a librarian role - review entries that are > X months/years old seems useful. So useful that I bet it's probably something people who are 'librarians' in a tech/doc sense probably do. I've just not been in orgs large enough to have people dedicated to that role. And... on day 1, it doesn't seem necessary. I was at a small startup in their year 5, and was initially impressed with all their internal docs, until about a month in I realized huge portions were vastly out of date, sometimes even just a few months after having been written. They were growing so fast "there's no time to keep it up to date!" but I was also often told "just go find X in the docs", yet... if I followed that info, it was wrong. So I had to find the docs and about 80% of the time, schedule a meeting with the author to confirm the docs were, indeed, still "correct". Moderate waste of time, but... "there's no time to keep it updated".
- BrandoElFollito 4y ago> Not sure you'd necessarily need to rely on contrast This was just an (extreme) example - what I meant is a way to make the users of the documentation pissed off enough so that they react, which in turn forces the author of the doc to update it.
- joshspankit 4y agoMy favourite documentation setup was when we decided to go “documentation first” . The entire team would use the documentation every time, and have permissions to modify as they went. We rewarded the “extra time” needed to open the doc and follow/update process every time. (in reality the ROI makes this an easy choice). There were even cases of printing off doc pages, writing on them while in the field, and updating the digital version. And it meant that we operated with “one brain” where the documentation always represented the most current collective knowledge. It was awesomely effective