Hacker News Reader

Comment by woodpanel | Hacker News Reader

Counterpoint: Confluence, by itself a great tool, just by hearing its name is making my eyes hurt from all the rolling.

I can't count the projects I took part in, in which the "knowledge database" had grown in to a gigantic, helplessly out-dated pile of words. Few people read another persons content, thus even less correct/update it. Finding anything usually involves scrolling through redundant search results and entries.

I know clean-code can't solve everything but I find self-explanatory code to be a major time-saver: less need to write documentation, less need to update documentation, easier getting an understanding of the code.

For everything more meta, there are still comments or e.g. infrastructure files. And ultimately the README.md. Looking into a package.json or docker-compose.yml often was more helpful if not a requirement to make sense of Confluence's content at all.

View on HN

How would you encourage a culture of reading?

(I also empathise heavily with the morass-of-distributed-documentation problem. a bit like coding, I think that although every code change should be documented (with reasoning, explanation, etc), organizations should try really, really hard to reduce the amount of written documentation required for products and services in the first place. a bit like the best code being the code that doesn't exist, it's much easier for folks to read and consume information when it's concise, well-organized and clear)

Collecting the signatures of readers at the bottom of important documents is pretty effective ;)

In my experience (as someone who enjoys both reading and writing) it's generally a question of demonstrating the concrete value of reading and producing written artifacts. I tend to start with teaching people how to write because it provides the most tangible outcomes: an outline, a plan, a draft, or a memo. When you're able to coach someone into expressing a raw idea of theirs as words on a page, the value of writing becomes clear very quickly.

From there, it's a matter of them warming up to the notion that internalizing the writing of others works in the opposite direction. Once they understand that reading and writing is the process of serializing and deserializing mental models (and that the result of this process is lossy at best, and actively misleading at worst), that's when the switch flips from "casual" to "critical" reader, and "amateur" to "practiced" writer, in my opinion.

> Collecting the signatures of readers at the bottom of important documents is pretty effective

Nice idea, thanks! Is that something you've seen implemented in practice? I'd be curious to see that combined with something like PageRank to determine document importance and credibility.

Back in the pre-internet era this is how bulletins and vital memos were handled in the airlines.

There were a couple of binders in the office for these & everyone had to sign-off on any new documents on their first duty shift since the doc was posted.

(Part of my job was to check the sign-offs and then tap the shoulder of any laggards to say, "Stop what you are doing and go read the bulletins. Now.")

I have seen it in practice, and I've done it in the past: the thing to keep in mind with this approach is that it's generally most effective when the contents of the document will have a critical impact on the reader's work, and when each signatory contributed something to its creation. In the wrong context, asking for a signature can come off as distasteful or overly bureaucratic, so it's best to avoid leaning on this as a common practice.

> reading and writing is the process of serializing and deserializing mental models

I'm gonna steal that one.

stock confluence can’t even import or export markdown files

I'm forced to use Sharepoint. I have a beautiful recurring dream where markdown export/import is my biggest problem.

Reply on news.ycombinator.com