Comment by phphphphp | Hacker News Reader

Comment by phphphphp | Hacker News Reader

I've not tried this at scale so it remains theory for me, but at a previous company, I proposed that we tackle this problem in the same way medical literature is managed by health organisations. That is, every page is owned and every page has an expiry: when a page expires, the owners are obligated to review it. The "yikes" part of that idea is that it feels burdensome, but that's because retaining and managing knowledge is burdensome and businesses should be measuring knowledge as an asset (or liability) and budgeting accordingly.

Ultimately, most people are digital maximalists when they'd be better off being digital minimalists. I (in my personal life and in the small teams I work with) purposefully delete things that I do not wish to accept the burden of owning. Either something is important enough to justify the burden of ensuring it's accurate, or it isn't and it is deleted.

I have found that thinking about documentation in these terms, it becomes clear what to document and what not to document, and it forces better practices elsewhere in the business -- like writing code that clearly communicates the why, or designing business processes that leverage a core set of business information.

As a technical writer of 9+ years I can share some concrete experience related to your theory. The theory is right on the money. Assigning an owner and tracking last review date is a very effective practice. Google had a great system (go/fresh-source) in their internal doc infrastructure, g3doc. I learned recently that parts of Microsoft have a similar setup. You put an "owner" field in the YAML frontmatter of your doc (the value is the username of the person who owns the doc), as well as a "last review" field (value is last review date). Then you build a reporting system that tracks who is keeping their docs up-to-date and who is not. You can ensure that people don't game it (e.g. just updating the "last review" field without actually looking at the docs) by cross-referencing with other metrics, such as number of bugs opened that are related to that area of the docs.

Yep. The same approach my org uses as well. There is a team, who deals with all orgs docs maintain it. There is a internal portal to submit and you start getting mails 2 months before expiry.

Respective team meetings, it's a agenda to talk about what needs to be updated, after updating a draft will be sent and later uploaded in the portal.

I think that expiry of documentation is a great idea, but it could go further:

- Often, teams "own" stuff but the real knowledge is stuck inside individuals. This type of thing would need to survive the relentless reorg cycle that seems ubiquitous in tech companies.

- The health sector seems to have longer overall tenures than the tech sector. At the very least this kind of system should somehow link into the HR administration, so that if a document owner leaves there can be an alert "This document is now unowned!". Of course, that alert also needs someone to monitor that.

- What would you use as a metric for the asset-ness of knowledge? Some types of knowledge seem more important than others, but it is not clear to me how to quantify that.

Your point about digital minimalism is very good though. A lot of things that should be deleted are instead kept around in a form of digital hoarding behavior.

I don't have a great answer unfortunately. My best attempt would involve walking back my use of "knowledge" as both an asset and liability, and instead I'd try to add some distinction, i.e: maybe describe "knowledge" as the asset and "documentation" as the liability.

Knowledge is something you consume, digest and then use to inform thinking. New knowledge is built on old, and business outputs can be traced back through the knowledge that shaped them. Documentation, on the other hand, is a statement of fact(s) that are applicable only in a specific context (often temporal) that do not contribute to the evolution of a business.

Liabilities aren't inherently negative, they're a valuable tool in the right circumstance: a piece of documentation written for a customer support agent describing "how to issue a refund" has value but it can't be leveraged to grow the business, it can't be built upon, and it must be maintained. The business then must make a tradeoff between investing in knowledge or taking on liabilities.

If we were to represent this visually, knowledge would be the branches of a tree that other branches grow from, and documentation is a dead end.

Most of the documentation I've encountered in my professional life has been written to meet an arbitrary requirement for there to be "documentation" about an output, and so it's a rushed recital of the bare-minimum facts about a thing that exists. Nothing can grow from it. Whereas, when I've encountered it, the knowledge used along the way has been very valuable. A business can create an asset by capturing everything learned, and leverage that asset to inform the next decision, and so on and so forth. After all, that's what individual employees are doing already, it's just happening siloed in their heads.

Returning to the customer support example: years of knowledge collected about our business might teach us that our product's sizing is unique in the marketplace and many customers end up refunding their first purchase to order a different size. If issuing a refund takes 5 minutes per customer, and if all we have is documentation describing the 10 step process, a request from stakeholders to improve customer support efficiency might manifest itself as software development work to reduce issuing a refund to a 5 step process... but knowledge about the business would inform us that what customers really want is to ability to find the right size that fits. Rather than make a documented process easier, we might implement a purchase option where we charge for 1 item, send out 2 sizes, and the customer returns the one they don't want to keep. If all our business knowledge is captured, and not siloed, then a new employee should be able to theorise that, not only an employee who has been around from the start.

I'm not sure how confident I am in the way I've framed this, and using the word "documentation" seems like a risk because "documentation" means "everything written down" to most people, but I appreciate your question because it was interesting to think about: maybe someday I'll have more clarity in my thinking on this.

The way it works on a typical QMS (quality management system) of the type you use in healthcare is when someone leaves the line manager or quality manager has to go through and reassign any documents owned by the individual (and they're always owned by an individual) to someone else. It's very much part of the normal rhythm of business and you have to do it because if you're working in medical / life sciences you need to be accredited, and as part of the accreditation your QMS will be checked to ensure it is up to date and there's no-one one there that shouldn't be.

As a slight extension of this line of thinking:

Every document is either "live" or a "snapshot".

Live documents have an expiry.

Documents are snapshots by default.

There's a piece of software (that I have no affiliation with) that has a feature like this built in named Guru: https://www.getguru.com

Oh my god, the expiry date is an amazing idea. So much of our data is never updated, and forcing the creator to update it or delete it before the expiry date would clear up so much old and outdated information.

I saw an intranet once that took this to the extreme. If a page went 30 days past expiration, it would only show a preview, then say something like:

"Only Bob Jones knows the rest of this story. Call him at x1234 to ask him about it."

Another advantage of the expiry date is that the owner - or his boss - can budget time to keep the docs up to date. It becomes as much a billable task as adding another shiny feature.

Reply on news.ycombinator.com