Ask HN: How do you share/organize knowledge at work and life?
I find it hard right now to share knowledge with everyone on the team and to turn knowledge into actual learnings.
I don't know how you guys do it, but I would love to know. We are now 50 people in the company and I don't know anymore how to make this scale. What is your process? Do you use any tool for it? How good is it? What needs improving?
303 comments
[ 24.0 ms ] story [ 7562 ms ] threadI would look at Standard Operating Procedures. They will greatly decrease stress and give structure to every process that’s important to your business, and make it easier to scale, onboard people and allow people to fill in for others.
Also, you iterate on these procedures. As you find improvements you roll them into the process and that way becomes the new way to do something.
If you just keep documenting and improving the improvements will be noticeable quickly.
I'd encourage "all" of the above in some flavour or another, as people learn and teach differently.
Only use mailing lists for notification with links to the actual knowledge in a real document.
The fact that I need to constantly look up how to do stuff and the modifications that I want to make work as I want them to only some of the time.
The fact that on more than one occasion, I've downloaded Emacs, started using it and gave up after less than an hour because of how unclear things are.
Some of us just don't want to 'invest' in tools that are profoundly flawed and will never be fixed, to the extent of causing physical injury.
Everything you are claiming is wrong. I came to Emacs from the Apple HIG shortcut world (which btw, Apple copied from PARC), and I think the keyboard shortcuts Emacs comes with are better thought out and more ergonomic to use. That is why they are the default (Emacs users prefer them), instead of cua-mode, which comes with Emacs and is easily activated.
Emacs key bindings are also far easier to change that in any other application, because Emacs keymaps are first-class objects with inheritance and are separate from commands. That is why Emacs can easily support not just completely different keyboard shortcuts, but completely different input methods such as modal editing.
Just saying that it's all so easy and making peoples issue with a complex editor like EMACS seem irrelevant or non-existing won't help anybody.
So, some alternatives to EMACS seem to be:
* for VS Code: https://github.com/vscode-org-mode/vscode-org-mode
* for vim: https://github.com/jceb/vim-orgmode
* for atom: https://atom.io/packages/organized
* sublime: https://github.com/danielmagnussons/orgmode
Also, some more information about integration can be found at: https://en.wikipedia.org/wiki/Org-mode#Integration
It can create entire wikis by rendering documents in many formats: For example:
- HTML: https://demo.filestash.app/api/export/hn/text/html/emacs.org
- PDF: https://demo.filestash.app/api/export/hn/application/pdf/ema...
- markdown: https://demo.filestash.app/api/export/hn/text/markdown/emacs...
- txt: https://demo.filestash.app/api/export/hn/text/plain/emacs.or...
...
Also, the document shown here is coming from this github repo: https://github.com/mickael-kerjean/nuage_org_demo and the app itself is free software: https://github.com/mickael-kerjean/filestash
It doesn't have all the features emacs has, but I'm quite happy with it for personal notes and simple TODOs.
There is another plugin for SublimeText [2] but apparently I like it less :)
[1] https://github.com/dim-an/Zorgmode
[2] https://github.com/danielmagnussons/orgmode
If you'd like to know more, either reply here or get in touch via my profile, I'd love to help you out (although it may be a bit delayed because I'm suffering from back issues right now). There's also reddit.com/r/emacs which helps a lot with org-mode stuff, much more than the org-mode subreddit. Plus you get to learn a bit of Lisp, which is pretty cool ;)
At work it's a mixture of mostly Confluence and Markdown README files.
Confluence's inline and bottom-of-the-page comments are excellent. You can have proper chained discussions.
Blog posts have been amazing for us to share small "experiences" like how somebody setup their environment (as opposed to more standard env setup documentation). These tend to be more informal.
Markdown files in repositories have been alright, definitely good for readmes. However, they suffer because our tooling (Gitlab) does not support comments on the files.
In my marriage, it’s my wife’s google calendar.
My personal projects are in a single google doc with tags I search for. I document my personal projects because sometimes I do stupid stuff and wipe out my work on accident.
For work, We use confluence as the source. We have daily stand ups that go on there. For any screenshare 1v1s I create a quick doc to cover what we discussed. We have a global team and even documenting everything will not suffice and you will need to meet on a screenshare. Record it for later reference.
I’ve been leading trainng sessions and they basically are a little technical stuff but mainly processes and where to go when you run into a problem. The best way to force people to use your wiki is to take time off or become unavailable for whatever reason.
You record your stand-ups on Confluence? I think retrospectives should probably be recorded (on something - Confluence I guess if you're using it) but stand-ups? Genuinely curious if you think you get any value from this? How often are they referred back to?
Our stand ups are for trending issues, global/timezone concerns, and really important things. They last around 15 mins. The notes we put in confluence are @mentions and the next steps.
Anything else is tracked in jira/salesforce.
THIS 100%!
https://github.com/sareiodata/kbexpander https://github.com/sareiodata/kbexpander-snippets
The tool is mapped to a keyboard shortcut (the OS manages this) and searches the snippet title and content. So you can easily filter down stuff.
The WP plugin also has reports, like most used snippets (every-time you paste a snippet, we track that) per user / date / category. This way we'll try to see in the future if we can improve a particular part of our product, improve inline docs so we stop getting those questions. I'm not sure if this will amount to anything, but it's something we're experimenting with.
Other tools exist, but I didn't find anything with good enough search + a way to have a common repo for snippets + usage reports, thus the Electron monstrosity and WP companion plugin.
This is how it looks: https://pbs.twimg.com/media/EG_Ejy9X0AAnnMV?format=jpg
But what makes it more powerful is scripting support. One can not only customize its look and feel using CSS but also modify its behavior with scripts. Its scripting system is very powerful, for example, one user has a build a version control system for the TW notes using the TW scripting language.
I use it as a personal wiki at work.
It even supports LaTeX (via KaTeX)!
Here are the customizations I found useful:
* Table of Contents:
By default, there is not Table of Contents in the wiki. So a TableOfContents tiddler was added.
The tag $:/tags/SideBar adds it to the nav bar, and the field list-before controls the position.
New entries are added to the table of contents by adding the TableOfContents tag.
Note: the same code can be used in tiddlers to list tiddlers with a given tag.
* Journal:
New Journal date format was changed to YYYY/0MM/0DD (DDD, MMM DDth). This makes lexicographic ordering of Journal tiddlers to be chronological.
That is, Journal tiddlers will be sorted by date when sorted by name.
Visual theme:
The layout was changed to fluid-fixed Settings - Appearance - Theme Tweaks - Options - Sidebar Layout: Fluid story, fixed sidebar
Sidebar width: 350px
This looks particularly well when occupying one half of a wide screen.
Appearance - Code Foreground was changed to #0a5701 (green, used to be red). This affects the color of text enclosed by single tick marks.
New Journal, Attachment, Configutation, Manager buttons were added
* Plugins:
The following plug-ins were added:
KaTeX for LaTeX support;
Highlight.js for code syntax highlighting
Does this help?
It's also really versatile. You can use it as a wiki, as a document hosting platform (like google docs), etc.
I add Google Calendar to it for time-based organization and Google Contacts for people knowledge. (I really wish this existed: A tool to aggregate my conversations across multiple mediums such as emails, tweets, DMs on various services etc and tie them to my contacts in Google Contacts.)
Not sure if this is still relevant, but at some moment they acknowledged their stuff access to client's data. This is huge no-no for any privacy conscious person.
Other that that it's a great tool for organising personal information for me.
It’s an alternative to Workflowy. Workflowy development stalled a while ago so I switched but it seems to be active again so I might switch back.
An infinitely zoomable hierarchy works really well for my OCD :)
There are some great "organizational" options in this thread though!
https://github.com/tannercollin/standardnotes-fs
For note-taking, I use https://wreeto.com.
We use fossil; a bit minimalistic, but you get a wiki + code repository + tech notes + issue tracking all in one place and auto-updated with the code, and you can run it as a server with a web interface for those who don't need permissions to clone the repo.
It's now all nice and tidy in a Confluence space. Let's see how it goes and how this holds up when more people start working on this project again. I for myself are diciplined enough to care about good documentation, but my last colleagues left a huge pile of chaos which took a few months to sort out after they left.
For the first use case, there are libraries available that sync your .md to Confluence which you could add to your CI system.
And yes, if your audience is programmers, then ideally you can hire technical writers who can program, and who can speak to programmers, but failing that, technical writers who can get proofread by a programmer can also work.
Having a single consistent voice is what matters, and that comes from giving a person the responsibility to be that voice.
It depends on the type of documentation of course, but if you work in a 50 person team and you want to document internal architecture or code structure, you better let the programmer that knows about the stuff write it.
First getting that technical writer up to speed about how everything is structured, the little implications etc, is pretty insane. It's like that phone game where you tell one person something, and then that one tells the next.
And then you go on to explain a way that it is more economical; Time is also an important economic consideration.
> First getting that technical writer up to speed about how everything is structured, the little implications etc, is pretty insane. It's like that phone game where you tell one person something, and then that one tells the next.
No. That's what happens when you have a non-technical writer do technical writing. I wouldn't have felt like I have to say this but just because someone has "technical writer" in their job title doesn't mean they can do that job.
If my colleague programmer works a week on refactoring some code, I honestly have no clue what was changed. There is only 1 person who actually knows what and why.
I also think that if you have developers working for a week without anyone who knows what they're doing you have a management problem.
We might be talking past each other, and I might not understand exactly what you're saying.
That explains why email is still the most used tool. It also sucks but you can do any type of project with email and everyone knows how to use it.
But we found that in the end - a normal wiki was actually more useful. I think this was mainly because of how our organization works. We're all physically on the same campus, at most a colleague is 2 minutes walking away. Hence we tend to often have in-person communication, or first via Slack, after which a colleague walks over to explain it anyway..
Using a wiki, the person knowledgeable about the domain can just create a document to refer people to which is quite natural. What is not natural for this person is to create a question and then answer it himself. (I know you could use SO as a wiki but than you're losing some of the utility anyway).
I'm not saying that it can't work, but a lot depends on company culture / structure, at least I think so. So if you're in a situation where people often post questions on slack and people respond through slack, maybe SO is a good alternative.
(Oh also, on another note, during our test people would post question on SO and no one would answer because no one is looking, or people think "someone else will answer" and don't bother to check up later. Via slack, at least it's more visible and scoped to the correct channel with the correct people for the domain).
YMMV ofc :)
At work we use Wikis for most things.
https://www.notion.so/Back-up-your-data-1a8eb5bdfce34d19a636...
Microsoft was using Mediawiki for external-facing developer docs (at least on the HoloLens site), but after the GitHub acquisition has switched to a workflow that uses VS Code as a Markdown editor & publishes to GitHub pages. That kind of workflow can be okay if all the people in your company are highly technical.
As your company grows you may get value out of internal conferences or mini TED style talks.
Video & screen recording can really help too.
Previously, I wrote papers and notes in a variety of word processors and page layout tools (Claris Works, Word, Apple Works, Pages, InDesign). Over time I’d miss an upgrade cycle, switch OS, or couldn’t justify the cost of an upgrade and lost access to many of those files. So far text files have proven to be quite portable across editor apps & I’ve also found writing in plain text helps me focus my thinking.