Ask HN: Is document discovery and staleness a challenge for you? | Hacker News Reader

Ask HN: Is document discovery and staleness a challenge for you?

11 pointsv1l10 comments

In my years of experience working on teams and now with client teams, I've observed this repeatedly: (internal) documents are written and rarely if ever, updated again. Worse yet, often no one knows some documents/wikis/memos exist, which doesn’t bode well for knowledge sharing and awareness.

The problem is particularly bad with Google docs (can never find anything) but not much better even if you're using Notion et al. May be it's that these tools are dumb in that they purely focus on the single document editing experience, not on the organization or consumption aspect of a document tool.

I know there's a people aspect to it, but I also know that if I'm not even aware of a document's existence and can't easily find it, there's nothing one can do.

Not looking for solutions here but more like thoughts or lived experience if you relate to the problem.

View on HN

My best-in-class example of document management is Xilinx (now AMD). Internally, they use an XML flow based on DITA - but the specifics aren't nearly as important as an apparent organizational commitment to delivering quality documentation. (They hire technical writers - these job postings are how I've gleaned most of the details about their documentation toolflow.)

In my small team, our solution has been:

- Commit to PDF as a documentation mechanism. Trying to co-maintain HTML and paginated outputs is too challenging.

- Maintain and track documentation in the same infrastructure as source code. For us, this means git and AsciiDoc (formerly, LaTeX). Asciidoctor to PDF via XSLT is crufty and slow but looks good enough and addresses most of our "wants" (table of contents, list of tables, list of figures, glossary, ...).

- Try to keep documents consolidated in relatively few repositories. A project-wide repository allows documents to share content (e.g. images) and encourages a coherent, consistent document tree.

- Provide a (hair-shirted, Makefile-based) mechanism to publish updated PDFs of these documents. Having a centralized publication site is critical, since it teaches people where to look and allows us to control document review/release cycles.

Purpose-built documentation management systems (e.g. Alfresco) might seem be better tailored towards documentation and might play nicer with Word, but it also keeps documentation in a ghetto and allows people to abandon it. Less is more.

Not now but at other workplaces. I was at one that had an all hands meeting every 2 weeks, the issue came up that “we can’t find anything”, the solution was “let’s add a new place to hide documents.” I tried to bring up the nonsensical nature of this, but people never wised up. Having ‘one ring to organize them all’ is a more promising solution but isn’t this an existential risk to the google docs, notions, confluences, etc?

What do you mean by "one ring to organize them all"?

also, just curious why isn't it a challenge now (presumably at your current workplace)?

We are well disciplined. We've been publishing open data for 75 years, we are an academic-adjacent organization, not a startup.

The "one ring to organize them all" is an "enterprising finding engine" as opposed to an "enterprise search engine". That is, an enterprise search engine built by people who think search quality matters and might also have some other navigation options.

I'm used to a lot of "Documents" being in the chat history on small projects. In practice it works perfectly fine, I can search. It's a bit scary though, if they disappear there could be a problem.

It's easy and frictionless to write, and I actually don't mind at all. I would be pretty much fine with a document system that started with a group chat like experience and added a bit more structure on top of that.

But really, more things could be self documenting. There doesn't need to be a document that says "This is the testing server and it is running this OS and has this IP", that kind of thing could probably be largely automated.

Code doesn't always need documentation, if you stop reinventing wheels and developing custom internal build tools. I don't need much documentation to run a Svelte project from github, the documentation is implicit in the fact you used an opinionated tool exactly as it was meant to be used.

It would be interesting to have a meeting, go over all recently used documentation, and figure out what it would take to automate it, and why it was needed.

Endemic in the industry. Especially at larger companies.

The gig I have been working at for a year, had a big ol document system. They're mostly written by folks who don't work here any more, and describe the previous generation of hardware/software.

They are a hint, a place to start, but every effort seems like starting over.

I don't think smaller companies are any better, especially growth phase.

From a software products perspective, these are the approaches I'm observing :

To keep that knowledge up to date, we make it part of everyday business processes.

    - documents that dynamically follow an active worklow : almanac.io...
    - wikis that cover the whole knowledge cycle : getguru.com, bloomfire.com...

To find relevant knowledge, Absent a forthcoming AI winter, deep learning magic is getting better and better at this.

    - Unified Search : dashworks.ai, needl.tech...
    - Expert identification : starmind.ai

This is a "hard problem," so I'm not claiming these kinds of products will solve it. But IMHO, we need such an effusion of market solutions to get better at it.

You've basically defined corp life. But yep it's a thing. In regulated industries though there will be a doc compliance org which basically stores official copies of approved documents.

Oh sweet jesus yes, if you could solve this you would make one layer of management obsolete and give the people 50% of their time back.

Reply on news.ycombinator.com