4 ms·
This is extremely hard though. It's not just some wave your magic wand around, or ask people to not be lazy anymore or something. Distilling knowledge, understa
by bonoboTP 3y ago
This is extremely hard though. It's not just some wave your magic wand around, or ask people to not be lazy anymore or something. Distilling knowledge, understanding where readers may be coming, seeing the big picture and keeping track of different moving parts, remembering and documenting their histories, all this is real work, real cognitive effort of the highest sort, on par with developing the newest feature or migrating to a new solution or whatever is seen as the "meat" of the work, as opposed to this type of lower-status "meta" work of just documenting. Often, "writing docs" is seen as junior work, something easy. Some parts are of course more straightforward, but a lot of it is very serious work that is underappreciated. And it's a vicious cycle: as long as documentation and technical writing is undervalued, smart rational actors in the company will just do the bare minimum of it and do something more visible and flashy that people do appreciate.
----
Also, I've seen internal wikis and the issue is that they tend to go stale, and people are afraid of removing information, and some people just don't know how to use a wiki and will start using it as a message board or like a Wikipedia talk page and add stuff like "Note by Joe: I'm not sure the above is still correct since the migration to XYZ. Alice should check this part", things not deleted but crossed out with strikethrough style, because "what if it will still be useful" (they don't understand the page history concept) etc. So it becomes a dump of horrible mixture of outdated and up-to-date info, where an experienced employee will tell you "oh it's in the wiki, just check it", then you go back to them that you can't find it or you found contradictory info and they tell you "ah, of course, you should ignore the page on bla bla, we should remove it soon, for this kind of thing you need to check the other page, and even though it says on top that it's 'outdated', actually this part is still valid".
The "curse of knowledge" is also very difficult to get rid of. It's really really hard to know where the reader is coming from. And what may be obvious and over-explained for one reader may feel like not enough detail or confusing to another.
- hinkley 3y agoI use a B tree strategy on wikis: As time progresses, the most relevant topic areas for the project consume the main page, and over time specifics get pushed down to subtopics and sub-subtopics. Anything that hasn't been touched in a long time is prioritized for moving down. If something has been sitting at the bottom of the tree for a long time and looks wrong, it might be time to delete it. But in the meantime you've made it harder to find. Once a page sprouts too many links it's time to halve it and push some of them down one level. Good activity for a Thursday or Friday afternoon when you've fixed a major bug and don't want to start anything new. The guys who need to toot their own horn want to put four links onto the main page. For some reason those scenarios live rent-free in my thoughts on Wikis. Probably because I was formulating this theory while working with one of them.
- bloopernova 3y agoHmm. That is an interesting idea, thank you for sharing it. We currently just have a big list of pages in alphabetical order after a short blurb. I'll need to figure out a new list order to implement. Hmm. Thanks for giving me something cool to think about!