Ah, I was thinking a different tactic: Everyone would just make mega-pages so that the page itself isn't stale but specific sections are.
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.
I've seen this with people that receive tons of email as well. They're out for a month and have 10k emails to sort through. Instead of doing that, they send a message to everyone who sent them an email that if it was important they should re-send. Then just delete everything.
My fear is that the wiki would be abolished/ignored in favour of each team maintaining its own internal documentation.
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've noticed that the number of bug trackers, like the number of wikis, seems to grow roughly logarithmically with respect to org size. It does also seem that as these numbers grow, the more teams revert to tribal knowledge, as nobody knows quite where to look for or create documentation.
We have a development team of 15 at most, but yeah, I get your point. Each project ended up having a different tracker depending on who was heading the department (also had three of those in a year).
It’s actually not that bad of an idea, it could be made less dramatic by auto-archiving stale pages, according to whatever rules you come up with.
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.
I tried to do this, but every time I suggested getting rid of the old wiki someone would object and say they checked it three months ago. It was still like this after it had been read-only for years.
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):
No. I concede that wiki rot is a problem, but just because no one has used a page for a year and all those involved have left the company doesn't mean the info isn't important.
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.
This is rather pointless exercise.
One can have a page documenting a very rare system crash and how to fix it.
If the crash don't repeat itself annually the page will be deleted. Not a great outcome, me thinks.
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.
We've used Guru[0] for some of our internal documentation, which will prompt you to re-verify the accuracy of docs on a set schedule. So every six months (configurable per doc), it will prompt the designated person to glance over the doc and say "yup, still good".
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.
I am a fan of Markdown based wikis.
Have been using GitLab for some time now.
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.
Alternatively: abandon wikis and keep documentation in your monorepo, next to the code/project it concerns (and in a doc/ global path for orga-wide documentation). Then render it with whatever - I wrote a little tool [1] for that, because I couldn't find anything that worked for this usecase.
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.
In most companies I've worked for only part of the contibuters to the company's Wiki were developers. What about Product Managers, BizDev people, etc?
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)
The solution to this is to make a UI which can be used like a wiki, but in fact creates a git commit for each edit. Allow documentation-only changes without reviews or pull requests etc.
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.
I may be in an unusual position of being able to dictate this but I always push for non-coders to use git and markdown... design assets are checked in to a repo, blog posts use markdown and are pushed to a Netlify site, marketers can tweak language and images directly in our Vue app (partly chosen for Vue's fantastic accessibility), etc.
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!
This would be insanity in a mono repo. A developer would have to look over every PR to make sure some critter from the marketing department didn't accidentally change an important bit of code.
1) You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage.
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.
> You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage.
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.
That's something your ownership and CI systems catch, and is a prerequisite to use a monorepo sensibly in the first place.
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.
I have no experience with monorepos - but yes, developers have to look over PRs that touch apps. No committing to the main branch!
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.
Alternatively, you could have some ui that allowed writing to the wiki and it converted it to a commit. Basically the same way that editing the readme can be done at GitHub.
In any case, as mentioned in a different comment. Most of the wiki is edited by developers anyway
Git is another level. But I have seen documentation of Linux systems in Google Docs. Commands, fragments of config files etc. This can burn your brain for sure.
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
This looks great and I wish my company adopted the monorepo & bazel. The navigation to //devtools from the link you shared results in a 404 however - perhaps the tool's routing is confused by the bazel "//<project>" syntax? Maybe not as I see the url path looks correct, maybe parent directory links should not show as active if there is nothing to serve in the parent directory.
It's broken :) This is mildly internal for now, and needs a bunch of bug fixes before release.
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.
I prefer this as well (except for the monorepo part :) ) for anything that concerns the code/app in any way. We chose Slab for our wiki partly because it can surface markdown files from github. So, the onboarding guide just links to relevant markdown files right in Slab.
One gotcha - if your playbook is stored there, make sure it's backup'd on secure external USB drives, as the source system, or the markdown render, or something else needed to accomplish this may go down, and now you and your team/project are going to be affected.
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.
What if your source system goes down, can't connect to your local machine, needs to use VM - no the oncall needs to have the USB stick or more, and use it any other company laptop.
Hackdoc itself has a mode to run from a local checkout, with no other service dependencies (vs. the production mode that expects a git/grpc proxy service to access the live repository), and as it's Go it can easily be moved around as a single, relocatable binary that will run from nearly all operating systems.
I feel like there's a vast difference between documentation relevant to code and a lot of the stuff accumulating in a company wiki. And if you put the latter in a global path, it doesn't become magically better maintained just because your wiki is backed by a repo.
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.
Your real documentation will always be your source code and configuration. Concentrate on making these clearer and more accessible (as appropriate, for instance, don't make your passwords too accessible).
Any other "documentation" should point to your real documentation.
Highly depends on your environment. If you have many products/projects, many things are worth documenting independently of the specific thing that encountered or used them.
I don't think you understand the purpose of documentation.
It's not to say HOW things are done. Code and config files are all overly detailed and often quite convoluted HOWs.
It's to explain WHY and to help people on the team orient themselves in a maturing product. It's to record thinking which went into deciding this or that implementation. It's to help people with HOW-TO recipes. It's to show the big-picture view of the project.
Code and comments in code are pretty much useless for these purposes.
Basically, any engineering org which doesn't pay attention to documentation is deeply disfunctional.
I suppose the idea here is that every wiki page is meant to be a living source of truth; and that no facts are better than outdated/incorrect facts?
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.)
Wiki rot is a real thing. The problem I've got with this suggestion is that it doesn't handle the case of pages that are useful but don't need to updated frequently.
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.
It's hard enough to get people to write these things down in the first place. The absolute worst case is "historical knowledge"; the piece of software that's just working, so nobody touches it, and the person who maintained it is leaving, so you need to get their knowledge in case you dig it up again. Which may be years later.
We use HelpDocs.io (love it) and they have a "set article to go stale" option. I haven't used it, but it seems like a nice reminder to re-evaluate or delete the page.
This is a terrible idea. You're destroying institutional knowledge because "it's cluttered."
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.
One of the most memorable experiences of my life was when I was moving out of a place and I had a beautiful loft bed with a slide for my son.
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.
This method acts as a forcing function to do exactly that because he tells his team to "recreate the pages they thought were important". If an organization's Wiki really is 75% irrelevant, unused, or incorrect, then a major correction is needed, and "declaring bankruptcy" seems like a good motivational tool to initiate a repair.
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.
To be fair, what the article proposes is more akin to a parent telling the kids, “pick up all the toys you care about, and anything that’s still on the floor by tomorrow is going to be donated.”
My question is why can’t the process be automated? Just make the whole thing behave like a cache with LRU eviction.
But what about the deleting clutter? In the analogy about the kids and the toys should the children be told to throw away toys they don't want to play with?
Fresh timestamps on the wrong answer defeats the purpose of a wiki.
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.
> To be fair, what the article proposes is more akin to a parent telling the kids, “pick up all the toys you care about, and anything that’s still on the floor by tomorrow is going to be donated.”
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.
This is probably the biggest unsolved problem in the "corporate wiki" space. It's easy to create content, but it's hard to organize it properly, it's even harder to re-organize a large mess, and it's harder still to have a person or team who's job is solely to manage document organization.
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.
A corporate wiki is the easiest and simplest form of corporate documentation you can have. If you really want proper, up-to-date, well-written documentation, a wiki isn't for you. A wiki is the first step towards proper documentation just above the "no documentation" stage.
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.
> IMO, the tools themselves are really failing us here.
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
I remember reading something somewhere that points out that Library Science is exactly about the skills to solve this problem: organizing, managing, and indexing large amounts of otherwise-unstructured data.
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.
> This is a terrible idea. You're destroying institutional knowledge because "it's cluttered."
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.
> 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?
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.
Indeed, this is the same terrible idea I see whenever my next job wants me to switch to the new latest and greatest javascript framework, or the new latest and greatest ML framework. If you never have time to build up the simple knowledge you keep wasting time.
Maybe one problem with a lot of Wiki software is they make the filetree-like structure seem too important with huge filetree sidebars and constantly make you consider the vastness of your outdated collection of knowledge. Why care if there are really old pages as long as their update times are very apparent?
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.)
Some kind of 'voting' could be handy - so you can see at the top of each wiki page "BobSmith last reviewed this page on 01/02/2007 and reported it accurate at the time".
This is more or less how my team handles it in servicenow. Any document that hasn't seen an edit or a rating in 90 days gets flagged for review. Every friday I clear the review list by either rating the doc or assigning it to a SME to be updated if I can't divine what the purpose of the document is.
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.
I could see a flag indicating whether you want to include archived content in the search index.
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.
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.
The problem with wikis in organizations is that they are a bit too unstructured.
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 ;-)
This is a pretty terrible idea. I've run a wiki at work and a lot of the information is outdated but a lot of it is also still really relevant even given that the page has not been touched in 3-5 years.
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.
I'm not familiar with Wikimedia plugins. In some plugin ecosystems there's an expectation that plugins need to adapt to deprecated apis, bump dependencies, etc. Is that the case for wikimedia plugins?
Regardless, 3 months seems like a very short time to consider something "unmaintained"
I'm a mediawiki developer, out of curiosity what was the name of your extension?
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.
At my company, every single PR is linked to a ticket. These tickets can be linked to each other as causes, related issues, etc. Having them around and reasonably organized has been invaluable for us since we can simply blame a change, trace it all the way back to when it wad introduced, and see why it was put there to begin with. Jira and our wiki system (Confluence) cross-reference each other where appropriate as well. Altogether, it makes the investigation part our jobs way simpler. I would not think to purge entries simply because they're older than an arbitrary date.
Facebook has this. Tasks are autoclosed after 6 months of inactivity, unless specifically flagged. It's sort of nice as a way to close things you were never going to get to, but it's also terrible if you actually have a long backlog but do want to get things done, because the auto closer adds a lot of noise.
This is one of the articles which is pure non sense, but helps drive a rich HN discussion on the topic discussed.
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
Terrible idea indeed. Why would I opt for a one year storage option when I could send an email blast with the info and have it retrievable for a lot longer?
I think what this idea is calling out is that whatever you sent in the email a year ago is probably stale now - it answers the question for that time, but not necessarily for right now, whereas a wiki should have versioning.
Unfortunately once you update the wiki, it also grows stale after that moment, so in someways intractable :)
Don't share documentation 1-1: Set your Slack retention ridiculously low to force people to put information in documentation if they wish it to be retained at all.
This is one of those instances of pure non-sense that I hope will drive rich discussion.
As with every other attempt to "force people" to do something via UX limitations, I think that's doomed to fail.
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]
The issue with 1-1 communication is not the retention part but the exclusive and not complete part. If you have no retention but allow 1-1, the same person will just keep asking the same question over and over. Which will make everything worst.
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
> Set your Slack retention ridiculously low to force people to put information in documentation if they wish it to be retained at all.
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 want to encourage thorough and up to date documentation? Don't allow code to be merged without docs. Review documentation at least as stringently as code. Insist on clear exposition, good grammar, and accuracy. If you're not willing to pay that price, your docs will only be as good as your programmers' intrinsic motivation to write them.
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.
I’m not sure if Wikipedia is a fair comparison but open minded - what I appreciate about this approach is it forces the org to think from first principles about what should be in their knowledge base.
What else do you see causing the problem aside from culture? Are there tools that do this well?
147 comments
[ 1.5 ms ] story [ 290 ms ] threadI 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.
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.
Would love to hear if anyone actually tried this
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.
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):
https://qiita.com/k_s/items/c7cee55dba4a74517232
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.
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.
Any other "documentation" should point to your real documentation.
It's not to say HOW things are done. Code and config files are all overly detailed and often quite convoluted HOWs.
It's to explain WHY and to help people on the team orient themselves in a maturing product. It's to record thinking which went into deciding this or that implementation. It's to help people with HOW-TO recipes. It's to show the big-picture view of the project.
Code and comments in code are pretty much useless for these purposes.
Basically, any engineering org which doesn't pay attention to documentation is deeply disfunctional.
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.)
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.
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.
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.)
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.
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.
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.
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.
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]
[1]: https://en.wikipedia.org/wiki/Desire_path
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?