5 ms·

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

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.

jka 5y ago
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)
- crabl 5y ago
  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.
  - jka 5y ago
    > 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.
    - AceyMan 5y ago
      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.")
    - crabl 5y ago
      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.
  - infogulch 5y ago
    > reading and writing is the process of serializing and deserializing mental models I'm gonna steal that one.
someguydave 5y ago
stock confluence can’t even import or export markdown files
- rodelrod 5y ago
  I'm forced to use Sharepoint. I have a beautiful recurring dream where markdown export/import is my biggest problem.

jka 5y ago

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)

crabl 5y ago
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.
- jka 5y ago
  > 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.
  - AceyMan 5y ago
    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.")
  - crabl 5y ago
    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.
- infogulch 5y ago
  > reading and writing is the process of serializing and deserializing mental models I'm gonna steal that one.

someguydave 5y ago

stock confluence can’t even import or export markdown files

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