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?
This is partially inspired by Chris Albon's excellent data science technical notes: http://chrisalbon.com.
I find it very helpful to have this kind of information on a public website. It's easy to search myself, quick to edit[^1], and helpful for sharing with others when someone asks me a question.
For notes I don't want to make public, I use OneNote. It's available on every platform, has a documented file format, and the sync works well. Of course, I have some more detailed notes on why I prefer this to other options: https://maxmasnick.com/kb/note-apps/.
[^1]: My whole website is built with https://gohugo.io. I use the GitHub Actions beta to automatically update the public site every time I commit to master. This means I can edit on a computer with a standard text editor, and also on iOS using https://workingcopyapp.com.
The link to where you explain it is broken: http://protips.maxmasnick.com/backing-up-onenote-notebooks
You mentioned it as being a critical feature but from what I've been reading, it's pretty complex and tricky due to it's weird syncing rules and relationship with OneDrive. The only decent solution requires a Windows version. See: https://answers.microsoft.com/en-us/msoffice/forum/all/good-...
https://support.office.com/en-us/article/export-and-import-o...
The simple answer is you can download zips of the entire OneNote notebook from the OneDrive web interface.
i've been experimenting with personal knowledge bases for much of the last decade and have settled on a homegrown solution that involves ten thousand markdown files. notes are organized as trees with a top level domain (eg. aws, programming, finance, etc) and finding a particular note is a tree traversal down the tree. the main goal is speed and structure - want to access anything within my knowledge base in seconds and have a coherent way of modeling knowledge even as it scales past ten thousand notes
recently quit my job to build this into a service. would love to get feedback from people with similar challenges: http://demo.alphacortex.io
How do you set that up?
The only potentially interesting part about this setup is I take advantage of this git feature I didn't know about until I set this up: https://git-scm.com/docs/git-worktree. This lets you essentially check out a branch into a folder in a repo. Hugo can then build the site in to the special folder, and the built site is committed just to that branch. I then push this branch to NFSN, rather than using rsync or scp, which takes a lot longer for small changes compared with sending a git delta over the wire.
I plan to write up a more extensive description of this when GitHub Actions come out of beta. If you want to hear about it when it comes out, you can subscribe to my blog's newsletter: https://masnick.blog/subscribe/
Deleted Comment
Deleted Comment
My Technical Notes blog (https://tech-notes.maxmasnick.com), which is a similar idea but much more random in content, does get a fair bit of traffic on specific pages, presumably via organic search traffic. (This is the most popular Tech Notes page, which has had 30k views over the last 4 years: https://tech-notes.maxmasnick.com/ipython-notebooks-automati...)
1) The system isn’t just “the wiki” or “Notion”. The system is composed of both the tools you’re using AND the habits/expectations of the humans who use them. So, this is not just a matter of buying a tool. Its a matter of choosing tools AND designing a process made of humans habits.
2) The system will get messy and unused unless there is regular attention & time allocated to tidying it.
3) If you want people to do something, recognise and incentivize it. If there is a person who habitually sends out concise notes after meetings, make sure that their performance review recognizes that contribution.
4) A habit has three parts: {:situation, :action, :reward}
Example:
Situation: At the end of a retrospective meeting, we have learned of a need for a runbook on how to handle a type of automated alert.
Action: The team lead updates a runbook and tags a junior engineer to review it for missing context.
Reward: The team lead feels satisfaction that they’ve set their team up for future success. They add a bullet point to the notes to use during their next annual review.
RuntimeException Map literal must contain an even number of forms clojure.lang.Util.runtimeException (Util.java:221)
For personal agenda I use Apple Notes with basically just a huge list of things to do and events that are about to happen and I curate that list more or less non stop during the day. If something comes up and I'm with people and don't want to be rude and spend too much time on the phone editing things to be in the right order and have all the relevant info captured with them, I just plop a line at the top of the note knowing I'll groom it later.
On my Mac, I can do the 4-finger swipe to check my full-screen notes. Usually I have a folder structure like notes/2019-10/2019-10-21.txt. If I want to tag things, I'll just write #idea #work somewhere in the text file.
Then easy to search with Sublime or whatever tool you want. I also like this approach because it's future-proof. Just a folder full of text files.
Curious how others are handling this same workflow.
Expect to continue updating/referencing it for decades to come, bar some calamity.
Deleted Comment
Oh, and one more thing: my Markdown documents are normally R-Markdown documents, so I can incorporate calculations and graphs as needed. (Also, R-Markdown has a nice metadata section for document title, author, date, etc.)
I find this a terrible workflow problem. As often a change to code requires a small or large change to documentation that is best bundled in alongside.
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.
THIS 100%!
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.
The original question was about sharing knowledge amongst a TEAM, but almost all of the responses are about PERSONAL systems. I know most people watching this board are small-company startup types (in general), but I'm hoping that some of the old codgers, like me, working in creaky, legacy firms, have more to say. If we can't find something off-the-shelf here, I'm going to wind up writing some kludgy homegrown tool with Elasticsearch, and, frankly, this just doesn't interest me. I need answers people! The leader for large teams, according to what I see here, seems to be Confluence. Notion LOOKS cool, but putting this data in someone else's hosted service is an absolute non-starter for us.
Private owned retailer: used Sharepoint and / or word documents on a shared network drive. This didn't work very well, but it ticked the "I did it" / corporate compliance boxes.
University: we use OneNote notebooks for each team. It's stored on a file share, and since everyone already uses Windows 10 / O365, it's an easy thing for our security concerns. It's also auto-backed up to the cloud (O365). It's also easy for business users / BA's to view and contribute to. Downsides: it's hard to flag info as out of date, or notify people of changes.
Healthcare provider: we used Markdown / Git. This worked because there was a single (mono) git solution for the entire org. Technically there was an SVN thing too, but the org was working to actively remove that / transfer source code to BitBucket. We required each project to have a README.md. This file included what the project did, and all the info a new analyst needs to know to get up and running: how to build the project, what servers it deployed to, what testing / production URL's applied to the project, what tools you installed on your local machine, etc.
We had a separate repository for "standards" that applied to all projects or across different global teams (think "internal" - EPIC, Sharepoint, etc teams and "external" product teams). These were just markdown files that contained policy info, best practices, libraries to use, etc. There was a "standards" team made up of a dozen individuals from separate teams that met quarterly to make updates to these standards. Changes were managed in Git and any issues were created there as well. It worked pretty well, since policy / standard changes tend to move slowly in large orgs. It also gave all teams visibility to the policies so they were all on the same page.
Sadly, a tool isn't going to get you out of this. You will end up with all the files uploaded to a wiki or repository. One would hope that seeing all the chaos in one place would make everyone say, "Oh, maybe we need to change how we do this," but that is unlikely. What will probably happen is, "This new knowledge management system is a chaotic mess. Let's abandon it."
I would completely ignore tools when you start on your plan. This is going to be a slog about setting expectations for how things will be decided, documented, and referenced, about getting managers and tech leads onboard to discipline their groups, and about having the whole thing not collapse into a bureaucratic nightmare.
Since you're shipping software, I might start with articulating the kinds of documents groups are expected to produce and keep up to date such as design documents that include why particular decisions were made, reference docs and docstrings to let users of a system find what they need, and tutorials/introductions to get users up to speed. Then expectations about how things should be recorded (in an expected class of document, not buried in a PowerPoint, and non-trivial examples).
Then you need buy in from management that engineers should put cycles towards this, and technical writing support to keep the whole think functioning. But think about behavior, not tools. User stories, if you will, of what kind of information people look for and when, and what kind of information people produce.
Very few tools are made for self-hosting or using mapped shared drives nowadays.
We run a server internally and all our documents are stored there.
The only thing that sucks about this setup is that you can’t fix typos without making a diff :)
The overall best knowledge-base I've ever used has been... Slack :-(
Email is probably second-best but suffers from too much spamminess—"here's a progress report you don't need, for that project you're kind-of on part time, sent once a week, to pollute your search results for same project if you ever actually need anything, oh and there'll be a 20-reply thread here which may or may not contain anything worthwhile to anyone at all, good luck sorting wheat from chaff". Plus if you have both Slack (or similar) and email Slack's more likely to have the Real Stuff, and email may miss out on entire topics.
It is reliable, flexible and has a pretty good search which works when you have multiple access levels. It's a bit clunky sometimes though.
- I can use my IDE in desktop to search / change them.
- On iOS, iA Writer can access to markdown files
- I get PRs to my public notebook because it’s on Github: https://github.com/azer/notebook
- The format and tooling are unlimited. Images, sound files, jupyter notebooks, everything fits
- It’s not binded to a product or protocol. I have freedom to personalize it and keep it the way I want.
- It scales beautifully. It’s been 3 years since I started it.
- The only problem was to have same IDE style for both code and markdown, I solved it later: https://kodfabrik.com/journal/ia-writer-mode-for-emacs/
I’d recommend it for those looking for alternative options.
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
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 ;)
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
Whatever you do, however, there is NO replacement for face-to-face discussion and interaction. There's no replacement for pedagogy that is as old as history itself: the Socratic method. The best way to learn something is for both the teacher and the student to ask and answer questions, to solve problems together.
Yes, it's true that it only scales like 1 -> N, where N is a small number. BUT, each of those people in that initial small "N" can also rollout knowledge if they've mastered it, if they have the right attitude about sharing knowledge, and if you trust them to do that.