Wiki Bankruptcy
critter.blog
critter.blog
The idea is a very bad idea. Imagine if wikipedia would do that, what will happen. Fortunately they don't and they found other way to fix the problem.
The issue here is: part of the documentation is not up to date anymore
The underlying issue is : the culture of the company probably doesn't encourage written documentation and probably prefer 1-1 communication. As a result documentation is out of date
The right solution is: Dont share documentation in 1-1, always write it on the wiki, and give the ability to people to notify that some part of the page is out of date so that the owner of the document can fix it
This is not a side issue, especially in the "new" world in which a lot of organizations need to work remotely
This would push people away from a wiki.
Unfortunately once you update the wiki, it also grows stale after that moment, so in someways intractable :)
This is one of those instances of pure non-sense that I hope will drive rich discussion.
The whole notion of forcing users to change their behavior by placing obstacles in their way is futile in my experience. It's a grave misunderstanding of who users are and how to design for them.
Forcing users to do what you want them to is how you get desire paths [1]
Also as the sibling comment is saying, you won't change the culture of an organization only by an UX change or a software change, that can help, but that won't be enough
I worked at a company that tried something similar.
The result was that individual teams set up their own off-the-record private Slack workspaces or Discords so they could regain some control over their conversation history. Obviously not great from a company information security perspective, but many managers looked the other way because they just wanted to get their work done without worrying about conversation history arbitrarily disappearing.
The idea that you can force people to produce better documentation by making their lives more difficult never really works out.
That's not the use case the blog post is addressing. It shouldn't be considered a mark against anyone if when applying their advice in a way that they never advocated then it turns out not to hold up so well.
You are restating the problem, the question is how
The fact that I have never been able to get buy-in for this proposal would argue that our docs may actually be good enough.
What else do you see causing the problem aside from culture? Are there tools that do this well?
In short, this is a terrible idea, don't do this. Even old and outdated articles serve as a historical record which can breadcrumbs for your mental processes as you troubleshoot an issue or understand the mindset that went into creating the system you're working on. "Outdated" just means that it's not an accurate representation of the current state, but it doesn't mean it isn't an accurate representation of historical state.
What did the company do after realizing it?
Somewhat wiki related but on the software side - I created a very basic plugin for wikimedia that solves a specific problem and because I did not have any commits in my github repo for 3-6 months they flagged my plugin as "do not use" and "unmaintained". It was frustrating to put something together in my free time and to have the community basically shun it because there were no new features I could think of to implement. I think documentation is the same way - creating friction by deleting, hiding, or even obtrusively flagging pages as "old and invalid" can make people not want to use your system.
Regardless, 3 months seems like a very short time to consider something "unmaintained"
Sometimes people get carried away with that process (deletionists are everywhere ;), but its primarily supposed to be for extensions that haven't been updated in a long time and don't work with the current version of mediawiki.
Instead of a forced page renewal there should be a bonus for fixing highly useful pages and a bounty for finding errors in the documentation.
Otherwise the same crappy page with few nuggets of useful links/info will be copied verbatim for ever and ever.
I'm undecided as to how well it works, but it seems like it a better solution to the stale data problem than "let's just delete everything and hope we don't ever need it" approach.
[0] getguru.com
On a separate note: one can script simple link checking/verification of the fetched content. And flag all pages with dead links, or with links where PDF/html/whatever did change from a snapshot taken say every month or so.
Lowering the effort barrier for documentation work (ie. making it easy, and expected for developers to commit documentation changes _alongside_ code changes) has been critical for the organizations I've worked with. Disorganized, slow-loading wikis with obtuse syntax markup tends to make people really not want to touch docs, or keep postponing cleanups. Developers will thank you for making the documentation grepable, for using standard code editing/review/submission flow for documentation changes, and for making ownership of documentation clear.
[1] - https://hackdoc.hackerspace.pl/devtools/hackdoc/README.md?re...
Do you expect everyone at the company to use git and work with markdown? (Don't get me wrong, I wish everyone did. But knowing people in these roles makes me think this would never happen)
Still use ACL's in the monorepo so that people can edit their own documentation with a single click, but to edit another teams docs requires some kind of pull request/approval from that team.
Create a culture that code changes must have accompanying documentation changes, and that any substantial code change without documentation changes needs a good reason.
Then everyone can use the tools they are familiar with, and still get all the benefits of history and always-uptodateness.
TBH I have not pushed non-coders to document stuff in git / markdown, only the developers do that.
Free, friendly tools like Github desktop, VS code, Netlify CMS help a ton. It also helps that marketers, designers, product managers are all technically inclined positions, where hiring smart people pays off.
There's a tradeoff as it takes more time to preach and teach the use of these tools, but I see it as a good investment for workflow and in people. Being able to wrangle git is a great skill!
2) It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team.
3) This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell.
Hard to catch everything
> It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team.
I'm all for open access, but systems should have safety rails to stop people from making mistakes. This is why we have the PR process in the first place. If you have non-programmers approving PRs created by other non-programmers into repositories that have mission critical code, then you're really just asking for trouble.
> This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell.
My position actually straddles product and development, so I spend much more time with marketing types than developers these days. They're fine people, but they aren't as patient and detail oriented as developers and lack awareness of the dangers of certain actions. I've seen them do all sorts of crazy stuff that would throw the security team into an absolute fit if they found out about it.
The ownership system ensures a per-subpath commit/review policy, while the CI system ensures a dependency change doesn't cause cascading failures in other parts of the repository.
Also what I have found to be essential to enable technical non-coders (and juniors! and contractors!) is that PR reviewers are responsible for merging and any needed final quality tweaks.
This isn't going to work with every team. Monorepos would make this whole effort harder, I'd guess that just teaching people what to edit would be painful.
Therefore Markdown should have higher priority than some crappy level Word or Excel skills. Even if 80% of endusers will use Markdown wiki/docs just as viewers, there is no point of hogtie sysdmins/developers and ask them to document in Word, google docs and keep data in excel files
The behaviour I would expect for this is that the 'devtools' part of the path shouldn't be clickable - as there isn't any documentation markdown in that path of the repository. I'll see if I can implement this today.
EDIT: fixed.
Google took this approach internally using markdown files (If I remember correctly).
Perforce is also going this way - https://www.perforce.com/manuals/swarm/Content/Swarm/basics.... - but I wish more (right now it's only in their "project overview pages.")
This allows for code reviews on the doc too, easier to auto-generate, fix, etc - than non-file interface like wiki.
Like pre-rendered to .html, .chm, even why not pdf files - whatever it takes just to be able for your oncall personnel to read them back if need to.
Yes: https://www.usenix.org/sites/default/files/conference/protec...
Age without further context is in any case a terrible indicator of relevance. What's IMHO important is a culture of providing the context with your entries.
I like the idea of marking all potentially outdated content as such. Maybe automatically archive old pages where it puts a "Warning: Potentially Outdated Content" notice to the top of any page that hasn't been updated in X months. Could also add a simple counter to the top of every page "Last updated XXX Days Ago" rather than the typical "Last Edited on <date>".
What do you do with clutter? You clean it. You don't burn your house down every year because it's cluttered.
Wikis aren't free. Organizations need to take it upon themselves to continuously groom the contents and organization of their wiki. They can be very useful if you do. But it's an ongoing process, just like organization in any other area in life.
You don't write code in a single file and then delete it when it gets too big. You create folders. You move and prune. Sometimes you delete. Make it intuitive.
If you can afford it.... It isn't the worst idea to just start from scratch.
I more or less gave it away (or... sold a $1500 bed for $50) and the mother who bought it cried because she said this is the nicest thing she has ever bought for her son.
So... If you can afford to do it, do it.
The 75% of articles nobody reads aren’t a problem. The problem is the 20% of articles everyone reads of which 80% is outdated or inconsistent.
This solution doesn’t solve that problem. The natural response to this policy is to copy and paste across resets. Not only does that do nothing useful, it risks adding more cruft.
My question is why can’t the process be automated? Just make the whole thing behave like a cache with LRU eviction.
I`ve personally seen a Fortune 500`s informal wiki/support infrastructure and knowledge consolidation is not as black and white as FIFO or GIGO (it was nonexistent aamaf).
Its rare to find an F500 company that has big data analysts working front-line roles to even get a grasp on a consolidation strategy, but shareholders can dream.
This works because the kids having one specific toy probably doesn't matter.
However, having one specific wiki page might matter quite a bit.
For example, how often do you perform emergency procedures? Is it often enough that you're going to edit the various emergency procedure pages in your wiki often enough to keep them from the chopping block? How about pages about things which aren't emergencies, but which are involved and delicate and require non-obvious knowledge? Again, how often will you edit those pages? Will you remember all of these vital pages every time the man comes around? Forget one and... You're on the hook for suddenly remembering everything which got deleted a few cycles ago.
They literally do burn it down periodically, and build another. Because they do this, and plan to do it, the knowledge of how to make it doesn't fade into history.
IMO, the tools themselves are really failing us here.
I'm creating a new document? Give me some kind of super-powered organizer algorithm. Auto-suggest the appropriate tags & folder/space location based on the content.
I'm an admin and trying to clean up the clutter? Run that same algorithm across the entire space and auto-suggest a better layout & document naming. Make it easy to bulk move/delete documents, folders, etc. Surface old, unvisited documents with no edits & recommend for archiving.
Search indexes could also take into account age of the document, # of edits, # of days _since_ an edit, etc.
I could go on.
If you want to improve on the wild-and-easy stage of everyone just using the wiki however they feel like, just have some rules.
For devops work, have a page for all your objects. Track lifetime events (the non-automatic kind) there. Swapped yet another disk in machine b47f8? You'll see the record in the wiki and can maybe also swap the controller or cables. Looking for the local installation procedure of some software? look at the wiki page. Doing another installation on a different host group? put a link in the wiki from hostgroup to software and vice versa. Have page templates for all objects and tasks.
The trick is "no change without wiki change". "No identical second support answer without wiki FAQ entry". The trick is documentation discipline.
(I know that some tasks may be better served with e.g. proper inventory software, however, there is something to be said for everything documentation-like in one place).
Oh, and ffs, never delete history, it will definitely bite you someday.
Yes but this is not the biggest issue. The biggest issue is the culture. In the short term it is easier to not have a proper documentation, so if you don't have an enforced culture about written documentation, this will always be an issue
It strikes me that all the various "corporate wiki" services are really just trying to patch over the absence of staff dedicated to this role.
It's also a terrible idea because, depending on the type of company and its lifestage, it might also be a colossal waste of time and energy even assuming wiki-rot is a problem you actually have (and that it's causing any damage which, honestly, is a moot point for many companies).
Are you really telling me, and especially now, with revenue down in the middle of a global pandemic and economic crisis, that the best use of everybody's time is to trash our internal wiki and start it again rather than, oh, I don't know, work on projects that we can actually charge people money for?
What I need most, right now, is for everyone to focus on making it raaaaaaaaaaaaiiiiin. That's not likely to change anytime soon, especially if the economy takes a protracted period to bounce back, as seems likely.
More generally I tend to be sceptical of people whose main output is corporate busywork[0]. If there's one thing any kind of recession makes clear it's this: the people you want are the people who either make a valuable product or offer a valuable service that can be sold, and the people who can effectively market and sell those products or services. Everything else is ancillary and, whilst you might need it, you want to run it as lean as possible. This isn't about being ruthlessly mercenary: it's about building a sustainable business with a decent buffer of cash that allows you to ride out the rough times so you can afford and keep paying people rather than be forced to make a load of them redundant.
As you've implied, keeping a wiki up to date is a cultural issue, and is something that needs to be done continuously. I think the key here is that sense of active maintenance, and encouraging everybody to be involved. If you change something and that something is referenced in the wiki, you need to change the wiki too otherwise the job isn't done.
[0] I imagine the places where wiki rot is most prevalent are those where creating the wiki in the first place was busywork - some sort of checkbox exercise, or a one off project with no thought given to ongoing maintenance.
I bet if you forced the managers to set everyone's OKRs or priorities for the quarter, none of them would include "Rewrite Wiki" in the written goals.
That's the real problem with these exercises: The intent may be good, but it's a massive amount of work that no one is willing to prioritize over other projects. So instead, the efforts stall out.
Furthermore, no one wants to contribute to a new Wiki if they think it will simply be discarded in a few years when the next up-and-coming manager wants to declare Wiki bankruptcy.
I worked at a company that was upset that too many people were relying on Slack backlog search to find answers to old questions. They decided to shut down the Slack workspace and start over new to encourage everyone to become less reliant on Slack. This solved nothing, but made everyone's jobs more difficult when they couldn't remember conversations from a few years ago.
Worse yet, many teams set up their own separate Slack workspaces, off the record, so they could have control over the destiny of their backlogs.
Nothing was solved, but many things became significantly worse.
My organization essentially does wiki bankruptcy every now and then simply by never agreeing on the informational tools we will use and constantly changing them. We have had three bug trackers and three documentation processes in a year.
It has made the wiki basically ignored as you don’t know what you need until you need it in many cases. We are back to relying mostly on the knowledge inside people’s heads.
> I use a trick with co-workers when we’re trying to decide where to eat for lunch and no one has any ideas. I recommend McDonald’s. An interesting thing happens. Everyone unanimously agrees that we can’t possibly go to McDonald’s, and better lunch suggestions emerge. Magic!
[1] https://medium.com/@jonbell/mcdonalds-theory-9216e1c9da7d
However, having active editors of sections with an incentive on people to contribute is good because it moves more info from closed spots to accessible spots.
I’ve never found a good, sustainable way to get librarians and editors. When I’ve gotten it to be people’s jobs it ends up being people out of touch who aren’t able to edit in a meaningful way. So we’d get perfect spelling and grammar but statements like “ visual studio is the top programming environment so all programmers must use msdn” that’s an obviously insane statement since we have lots of non-MS devs, but the editor didn’t know that, left it, and caused lots of confusion.
The BigCo I work at tends to decide, every couple of years, to change Wiki platforms and more or less delete the previous Wiki. The new Wiki starts with some beautifully polished pages anointed by the high priests of information. Some other useful pages make it over (usually losing considerable historical context). Some other pages get lost, because the people most qualified to maintain them have moved on. Other pages get lost because the people most qualified to maintain them get tired of getting jerked around.
Better solution: stop using big branded, overly clever and difficult to use wiki software. Have a single wiki, not split artificially by project, that can be searched as a single entity.
Old content is still handy to have accessible, even if it’s not completely accurate, but it makes searching awful.
I don't think there's any way to curate an evergreen wiki that doesn't involve some regularly applied TLC. It's like doing your dishes and vacuuming the rug.
You could make recency a factor in ranking though.
But more generally, archived content would be where you’d browse for content you know used to be available. Anything that you know should be searchable is the content that should be migrated each time bankruptcy is declared.
Internals documentation is a subject I have given up on. Everyone has wildly different opinions on what it should contain, and how much of it there should be. I keep my own notes and just pretend most of the internal wiki doesn’t exist to stay out of it.
When a company is small they are great, but they accumulate cruft, the people who wrote the pages leave, they get disorganized, no one knows where to put pages, no one can find anything, etc, etc.
So when you look up something in the wiki you don't know whether it is up to date or not. Maybe it contains a procedure written by the support staff which you need to follow when X happens but the developers have changed the subsystem so it is actively dangerous now?
As orgs grow and their data grows you need a more structured place to put it than a wiki (or the shared filestore for that matter, ewww). One day you'll have Compliance requiring that docs are kept up to date, organized properly and owned by somebody.
Eventually you'll end up using a more sophisticated tool like Confluence which can enforce ownership of pages, enforce structure, archive pages which aren't updated and generally tick the compliance boxes.
(The above my personal experience from growing a company from 0-50 staff ;-)
And it's hard to structure anything that works on all of the axis that people want to view the information.
I was, and still remain firmly in the wiki camp. If you find information out of date date in a wiki you can flag it, comment on it or update it. Wikis are not a "single-source-of-truth". The effort to make everything authoritative and run through 20 layers of approvals kills the will/time/ability to document things and tosses tar into the speedy gears of your documentation machine.
So you have articles from 10 years ago? are they hurting you? No they are not- just because 12 editors did not find them useful does not mean that the 'irrelevant' out of date article from 10 years ago wont help the oncall getting paged at 3AM. Keep your stale data. Lessons learned and documentation of old things can find new ways of being important long past the time that they served their core function.
Storage is cheap. No need to be a deletionist- you gain nothing. What you loose is history and perspective.
Personally I had plenty of documents I would look at that were over 6 years old and I was very thankful to find something from the past- "Ohhhh so that is why we chose this architecture!" so now I can say "Yeah, I actually found out why we did things this way- we no longer need to do this and should revisit how we stand these things up."
What I see is a 3-4 year cycle/tenure/promo/depart on good engineers. If your history only goes back that far then you are basically losing history every generation of engineer. For what it is worth, in my experience, most of the people who propose this sort of thing have never been on the other side of the pager at 3AM.
In general, what's worse than having outdated information is having information vanishing, so that you have no way of validating how appropriate it is. Out of date information, whilst not spelling out the correct process, may give you an idea of the steps involved.
Anyway to implement this you would probably do something like:
git log -n 1 dir/file
As others in this thread have pointed out, if you have a page (or twenty) in your wiki that capture information about arcane information that doesn't have even yearly applicability -- yet still may have applicability -- by deleting it you've willfully destroyed some organizational knowledge.
Just as bad would be cases where editors don't even know if the information is still important, but due to the timestamp choose to delete it.
This is as about as close to "throwing out the baby with the bathwater" as it gets.
- A wiki reaper that would reap docs that hadn't been updated in more than 1 year. We'd give people 1 month to action.
- In search, older pages were weighted lower than newer pages.
- Pages had "team" owners rather than individuals.
- Teams would get a monthly digest of their top viewed pages and lowest viewed pages to encourage updates.
- Star rating for pages 1 through 5, would feed into above digest.
Wikis grow organically but need active curating.
If you are a distributed company, even outdated and wrong docs are more useful than nothing at all.
The bigger issue that I see is that keeping internal documents in a good state is hard and it's no ones responsibility usually. I've been on teams where the internal documentation is great but it's always been because one person has put a ton of time into maintaining it.
* giving readers the ability to quickly highlight some text/content to mark sections as "out of date"
* provide "rot report" views where maintainers can see which pages are the most stale in terms of never being viewed or edited. Sort of highlighting of content which has gone the longest without being seen at all (or possibly, edited).
For our engineering team we've been happy with StackOverflow Teams. Some of the questions are probably just as outdated as the author complains about, but with the design of SO it doesn't matter much. We use tagging heavily and make sure to include keywords in the content of the questions and answers.
One downside of SO Teams is that you are subject to SO's search engine instead of Google or your search engine of choice since your team's pages are private.
(I'm not affiliated with StackOverflow, I'm just a customer.)
I think the best approach to this problem I've seen is an Last Edited date (or preferably, activity graph or "N" edits in the last year or similar) at the top that gets increasingly obnoxious as content gets more stale. Obviously far from perfect, but would have saved me from relying on out-of-date documentation many times.
If anyone happens to mention to me how it's after 4 and they don't want to start anything new, I suggest they clean up the wiki a bit.
Start from the landing pages and project pages. Every page should say what it's for right at the top (that way I know when I've gone to the wrong page). Any page that is too long or has too many outbound links needs to be simplified. Any content that is not about that subject, should go to one that is. If you spent 1/3 of a page about one topic talking about a different topic, that page has been hijacked, and it should be fixed.
Eventually all of the dead content is 5 links away from the root, the contemporary stuff and the things that are always true are a few clicks away from the landing pages. At this point it barely matters if old stuff is there.
In that case, I'd offer an additional suggestion: rather than deleting the wiki, just add some flag-bit to pages to hide them, where un-hiding them requires an edit. (Sort of like the flag-bit on user-accounts that means the user needs to change their password before they can log in again.)
Then, add a plagiarism filter (that is only active during these edits), such that during that re-enabling edit, the user cannot accept any of the previous text as is, but must at least paraphrase it. (Just like, in that "must change your password" mode, you can't reuse your old password.)
This would hopefully force the user to consider the value of everything they're re-writing as they're re-writing it. It incentivizes deleting, because deleting is less work than keeping; information would only be kept if it "pulled its weight."
You could even make the process easier, using a bit of client-side JS to run the user through the text of the original hunk-by-hunk ala a `git add -p`: show one sentence at a time, and require that the user type it out again if it's true; write a corrected version if it's slightly incorrect; or "drop" the line if it's now useless.
As for who exactly would have the responsibility of doing this, two considerations:
• Corporate wikis don't tend to have people whose full-time role is to edit/maintain them, ala Wikipedia editors. If they did, it would probably be such a person's job; but that'd also imply that such people would need to be "lore gatherers" for the company, such that they know what is outdated/incorrect. Sounds hard.
• While wikis are designed to enable a shared contribution model, I feel like corporate wiki pages can usually be said to have one main "owner" who has a "responsibility" for them (sort of like a component in a source tree does.) Perhaps it could be that person's responsibility to "refresh" the wiki pages for which they're the "owner." (Hopefully they're something like a product manager, where things like this—communication to ensure productivity—is already what they do all day, and this isn't getting in the way of other tasks for them.)
- find pages that haven’t been updated in a while
- messages the last editor “this page will be deleted in a week. If you think is should be kept please update it”
- a week later deletes the page (or puts it an archive)
Probably needs to smart about how it determines age - certain pages tend to get used annually only (eg the annual budget info)
All that said, most of the problem of cluttered corporate wikis is simply because their search engines suck. Confluence is particularly bad.
The #1 thing you need in a corporate wiki search is results ranked by recency ... most things that happen in a corporation have a half life of 2 weeks before they’re no longer interesting. Relevancy also comes into that of course. The user themself would also be nice to have - a given person with a given role will naturally be more interested in some content and not others, and that’s easy to determine from their search history
In that case, I’d rather have the chaos of a wiki as long as there’s version history that shows users. That at least improves the asks to individuals and helps find the mavens of info.
So I’d rather just work on a wiki with search and let the organization happen organically than “burn it down and start over.”
I find it really hard to get the right people to contribute as superficial info from non-SMEs or some contractor whose job is to crank out docs that don’t have usage metrics or quality metrics is worse than nothing.
Currently I’m trying out, not a wiki, but a git repo that takes pull requests and generates a web site that’s hooked into intranet search. It allows easy read and any employee can send a PR or open an issue so all changes are tied back to a specific individual.
I slowly found myself searching Slack for answers and the search is pretty good. I'm sure deprioritizing older messages and posts is built in to the index algorithm but the messages are still there for if I need to go back that far.
I hate to shill for Slack but this is the closest thing I've found to a Stack Overflow/Google substitute for enterprise knowledge. I usually arrive at these conclusions through experience and test feedback loops.
Confluence I've found is tolerable for static documents like business requirements but the UI feels stuck in the early 2010's and isn't as usable as it could be. Google Docs and Sheets seem to suffer from discoverability issues at a bunch of the places I've worked at.
Would love to hear if anyone actually tried this
The term is outdated but the need is not: to tame this kind of thing, you need a webmaster, a person who has been granted the authority to create structure, to move things, to say "This belongs somewhere else" or "If you don't update this I am going to take it away." This is a person who has a responsibility to run a link checker and to see when the last time a page was accessed.
It's a real need, but we just forgot about it during the fragmentation of all things web-related.
For longer prose and procedures (particularly troubleshooting a very specific problem) I am encouraging blog posts with tags that link back to the parent page. These degrade more obviously due to their chronological nature and feel less jarring to prune (which can be done simply by changing the tags).
There's a Japanese site for tech blogging called Qiita that puts a warning at the top of any post that's over a year old. While a scorched earth policy could be more satisfying (and potentially safer), using a warning might make it easier to get buy-in.
Here's a random Qiita post with a warning (yellow box):
The author's justification (at least in part) for deleting all of this information? It can be bad in the hands of employees which aren't intelligent to recognize the fact it is out of date. The solution? Trust those same employees to recognize that even though they know how to perform a completely obscure process, they should download a Wiki that they never use but will be incredibly important in the case of their own death or departure.
Absolutely brilliant.
Archive old pages compressed heavily but in he wiki data store. Mark them as potentially obsolete but possibly of historical interest. Leave links to them intact and have an option to restore the page to intake status for viewing.
Assigning pages to owners is also important, so you know who's responsible for the content. In Confluence we just use Spaces as logical groupings but YMMV.
It doesn't solve all the use cases of an internal wiki (yet), but the main idea is, if you rely on people to keep a knowledge base up to date, it will fall into disrepair pretty fast. So you need to integrate with their workflow and make this extremely seamless.
And if someone gets there and wants the old version back, they can.
Misuse of the medium:
- It's used as a repository for product requirements (which are usually either stale, or may actually be speculative of future incarnations of a feature. In either case this is usually linked to as reference acceptance criteria in JIRA tickets, which creates all the problems you'd imagine).
- It's used to hoard information about what X team did to get something done according to another team's processes (i.e. getting secrets added to our secrets store, how to add a piece of infrastructure, etc.), which have likely changed since X team went through this (and the reference material is rarely ever linked to).
- It's used to document abstractions in code, and is usually stale as the code and documentation are not reviewed together in pull requests.
Lack of ownership/maintenance:
- All public confluence articles appear to get indexed in search (and they are by default published as public), and however search is configured it seems to be very bad at determining relevancy, so you are just as likely to get someone's stale instructions for how they followed some internal procedure as you are the owning team's documentation for doing it
- There seem to be no standards for what information needs to be provided in documentation about internal APIs. No consistency on providing information about request/response types, parameters, contextual/semantic information, limits, true SLAs (as almost everything advertised as an SLA is an SLO), downstream dependencies, etc. This may actually be a "wrong tool for the job" instance too, but in the absence of any other consolidated way of documenting APIs, this is the best thing this company has.
- No one seems to be responsible for culling stale information, and since hoarding is so prevalent, people are reluctant to actually do it. Sometimes I come across stale information in articles published by users with deactivated accounts, sometimes the only indication that the information is stale is that someone has added "(Archived)" in the title (or something similar), sometimes there's just a banner on the page saying something like "this information is no longer valid, see other team" and then linking to the wrong place to find the current information, etc. All of these pages still rank highly in search results.
There may be several organizational dysfunctions involved in creating this state of affairs, and you should have a plan for incentivizing good wiki maintenance and proper use that is a more complicated and sophisticated process, but generally I'm in favor of more radical plans to cull stale information when you find yourself in this kind of situation (if you can get buy-in). This is fundamentally different from crufty old code, because there's nothing battle-testing bad documentation like old code is battle-tested by reality, and stale information is effectively disinformation and it propagates all the usual costs of disinformation (slowed retrieval of necessary information, ill-informed decisions, etc.).
Any other "documentation" should point to your real documentation.