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
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.
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?
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.
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.
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?
Sounds like one of the people at a former employer of mine had a time machine to come forward in time to read this article and take it by heart. He deleted more than 800 articles I had written on the company wiki, which were never recovered, and then when he eventually left the company it was realized that those articles were important reference points which were never replaced in the transition. It turns out deleting 800 articles is easier than writing 800 articles when the original author with the domain knowledge had moved on into another role.
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.
> Sounds like one of the people at a former employer of mine had a time machine to come forward in time to read this article and take it by heart. He deleted more than 800 articles I had written on the company wiki, which were never recovered, and then when he eventually left the company it was realized that those articles were important reference points which were never replaced in the transition. It turns out deleting 800 articles is easier than writing 800 articles when the original author with the domain knowledge had moved on into another role.
I have problem comprehending how a company which requires hundreds of wiki pages to function somehow does not have if not versioning system then at least a weekly backup of essential documentation.
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 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.
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"
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.
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)
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.
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.
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.
Biggest issue with this is that it destroys all history about technical decisions/processes/etc. I regularly find myself looking through old documents to figure out why something was set up the way it was.
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>".
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.
> 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.
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.
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 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.
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.
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.
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.
Brilliant. This is like the McDonald's theory. [1]
> 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!
This is the prototypically terrible idea that "information architects" love. There is an underlying streak of distrust of any information not curated by a professional, and it's fundamentally antithetical to Wiki values.
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.
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.
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.
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 ;-)
I think the core problem is this: In building ANY documentation you have a slider between cost, freshness and accuracy. You can pick any two. You can NEVER obtain all three. My last place of work was a large FAANG and we had multiple knowledge management systems.
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.
Instead of deleting the pages, why not premise them with something like "This page may contain outdated information" after some timeout condition? It seems like this solution would really solve this problem...
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
Check the date, if it's larger than some amount and grep doesn't show some existing warning, throw a warning in the header of the 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.
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.
I wonder if there is any wiki software that would actively help curators in grooming it by say:
* 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).
[+] [-] polote|5 years ago|reply
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
[+] [-] VectorLock|5 years ago|reply
This is one of those instances of pure non-sense that I hope will drive rich discussion.
[+] [-] godzillabrennus|5 years ago|reply
This would push people away from a wiki.
[+] [-] sevensor|5 years ago|reply
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.
[+] [-] kindofastrawman|5 years ago|reply
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.
[+] [-] harrisonjohnson|5 years ago|reply
What else do you see causing the problem aside from culture? Are there tools that do this well?
[+] [-] thinkloop|5 years ago|reply
You are restating the problem, the question is how
[+] [-] tristor|5 years ago|reply
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.
[+] [-] searchableguy|5 years ago|reply
What did the company do after realizing it?
[+] [-] elmolino89|5 years ago|reply
[+] [-] IE6|5 years ago|reply
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.
[+] [-] bawolff|5 years ago|reply
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.
[+] [-] EE84M3i|5 years ago|reply
Regardless, 3 months seems like a very short time to consider something "unmaintained"
[+] [-] elmolino89|5 years ago|reply
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.
[+] [-] lkbm|5 years ago|reply
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
[+] [-] kholterhoff|5 years ago|reply
[+] [-] q3k|5 years ago|reply
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...
[+] [-] matanrubin|5 years ago|reply
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)
[+] [-] malkia|5 years ago|reply
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.
[+] [-] detaro|5 years ago|reply
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.
[+] [-] tln|5 years ago|reply
[+] [-] mancini0|5 years ago|reply
[+] [-] dcchambers|5 years ago|reply
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>".
[+] [-] MAGZine|5 years ago|reply
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.
[+] [-] bartread|5 years ago|reply
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.
[+] [-] Hayvok|5 years ago|reply
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.
[+] [-] JulianMorrison|5 years ago|reply
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.
[+] [-] programmarchy|5 years ago|reply
[+] [-] qzw|5 years ago|reply
My question is why can’t the process be automated? Just make the whole thing behave like a cache with LRU eviction.
[+] [-] DiffProg|5 years ago|reply
[+] [-] cheez|5 years ago|reply
If you can afford it.... It isn't the worst idea to just start from scratch.
[+] [-] unknown|5 years ago|reply
[deleted]
[+] [-] MattGaiser|5 years ago|reply
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.
[+] [-] justhw|5 years ago|reply
> 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
[+] [-] guessbest|5 years ago|reply
[+] [-] microtherion|5 years ago|reply
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.
[+] [-] RegW|5 years ago|reply
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.
[+] [-] macintux|5 years ago|reply
Old content is still handy to have accessible, even if it’s not completely accurate, but it makes searching awful.
[+] [-] corytheboyd|5 years ago|reply
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.
[+] [-] nickcw|5 years ago|reply
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 ;-)
[+] [-] richardwhiuk|5 years ago|reply
And it's hard to structure anything that works on all of the axis that people want to view the information.
[+] [-] crmrc114|5 years ago|reply
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.
[+] [-] bArray|5 years ago|reply
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:
Check the date, if it's larger than some amount and grep doesn't show some existing warning, throw a warning in the header of the file.[+] [-] MrZongle2|5 years ago|reply
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.
[+] [-] scottmac|5 years ago|reply
- 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.
[+] [-] disgruntledphd2|5 years ago|reply
If you are a distributed company, even outdated and wrong docs are more useful than nothing at all.
[+] [-] jrott|5 years ago|reply
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.
[+] [-] joshlemer|5 years ago|reply
* 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).
[+] [-] mch82|5 years ago|reply
https://en.wikipedia.org/wiki/Special:SpecialPages