Ask HN: How do you share/organize knowledge at work and life?

We used to use Confluence but it always felt too bloated and cluttered. It was a pain to get people to contribute and even harder to find stuff because of how slow and broken the search was.

We have since switched to Nuclino (https://www.nuclino.com/) and are pretty happy so far. Refreshingly simple, lightweight, and focused on getting the essential features right. We are now moving away from Google Docs as well and trying to consolidate all knowledge in Nuclino. It’s almost perfect for our needs, only a few nice-to-have integrations are missing (and will hopefully be added soon).

Finding the right tool is only half the battle though, getting people to actually use it and keep the content up-to-date is usually the real challenge. Switching to a more user-friendly tool certainly helps, but it isn’t enough to create a culture of documentation.

For any system you build, keep in mind two general truths:

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.

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.

I use Markdown documents in Git repositories whenever I can. Also try to evangelize for this at work. PRs then include relevant changes to both code and docs and it’s beautiful. For personal project docs I use this exclusively. At work it depends on the team, some people don’t like it, but most often it is because they don’t like keeping docs at all, not because of an alternative preference. I avoid UI and WYSIWYG based systems like Confluence like plague. I personally can’t stand them and every time I have to use one I do my hardest to pretend I’m writing Markdown in my head.

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.

This is pretty much exactly what I do, too. The only difference is that my use of Apple Notes is mostly for quick, personal things … I move material into Markdown documents within git repositories as soon as I can, because then it’s easy to share it, trace changes, and organize contributions.

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.)

Notion: https://notion.so

Notion is our single source of truth.

It makes a good wiki because adding, editing, and organizing information has such low activation energy. Each part of the org (Eng, Community, Marketing, People, …) has a tree of pages with process, information, etc.

We have a few big centralized databases that everyone uses:

– Tasks. Lets us see what anyone is doing, assign tickets, track progress.

– Documents. This one has a weird name. All teams put meeting notes, research, proposed designs, RFCs, specs in this database. The common thread here is that documents are artifacts of their time: they’re authored, reviewed and commented on by the team, iterated on, then ratified or archived. We rarely change them afterwards because they store historical context on decisions. If an RFC changes a process, or a design gets implemented, the affected team(s) might update their wikis.

– Goals. Stores objectives, product use-cases, and large projects. We relate Tasks and Documents with the Goals they support.

Centralizing these databases fosters cross-team visibility and assists with collaboration, eg seeing Eng and Marketing tasks related to an upcoming launch, plus the designs and research.

Shortcomings:

– Search. At the ~50 person size it isn’t a desperate problem but it does hurt.

– Integration with email and calendar. There’s no way to sync Notion to Gcal or react to incoming emails.

– Integration with Github: none.

– Mobile performance could be better.

[Disclaimer: I work at Notion.]

IMO you should disclose (and it is a disclosure, not a disclaimer) your employer at the top, because it makes the rest of your comment something nearer to marketing copy than user review.

I agree: this trick of saying that you are using Notion as a source of truth when you work at Notion had left a bitter aftertaste, on a product I should love overwise.

I love the product but I’ve not been able to switch all my note taking to Notion due to the lack-luster performance of the mobile (Android) client. It’d be fantastic if the app could cache data more aggressively enabling more fluid interactions.

I would love to use notion more, I like the way it works, it’s flexibility, and would happily pay, unfortunately your offline capabilities arnt as good as I’d like it to be, and importantly your app startup time is very slow (which you already called out)

Will keep checking in in the future. Keep going though!

Hey I’ve been using Notion at work and its great so far. Do you know when will the api will be ready by?

This looks really nice and quite useful, you should do a Show HN! (By the way, that first link doesn’t work)

You can’t use Emacs as notepad.exe, and comparing it with vim shows how low you’re setting the bar. Out of the box it doesn’t even have standard ctl-zxcv shortcuts. The keybindings it does have are terrible and give RSI, and crucially because there’s a whole ecosystem of addons that try not to collide, they can never be changed, which is why CUA mode isn’t default.

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.

Why are you comparing Emacs to primarily modal editors? This discussion is not about those.

> what makes you think Emacs has a high learning curve?

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.

The default configuration of both ViM and Emacs are both pretty unerognomic. And both can be configured to work in pretty much the same way. Both have plugins.

I would suggest a single source of truth.

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.

I use Notion (https://notion.so) for pretty much everything (budgeting, tracking my PhD progress, high-level work-related projects, financial planning, etc). It’s so flexible and has all the features you might reasonably want for managing information etc. It’s essentially Evernote and Trello in one beautiful tool.

At work we use Wikis for most things.

To bring some structure I think the tool is less important than having procedures to provide a framework for everything.

I 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.

Create a knowledge-team whose sole job is to take information from all the other teams, digest it, and make it available to the rest of the firm. Call it “corporate communications” or “internal marketing” or whatever floats your boat. If you can’t get a proper department, at a minimum you can get a on-staff librarian who is a good technical writer who you can pass around the firm (as long as they have the ear of the CEO/COO).

In a programmer environment, this is impossible. A programmer will always need to document his own things for a simple reason: (s)he is the only one who really knows. Putting people in the middle of that who can barely understand all the details, seems like a lot of overhead for a worse deliverable.

It’s a great tool. All the information is stored inside a web page, which in turn means I can view it on any device that has a browser.

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.

Putting all your company’s data in a random startups hosted service is something not everyone can and should do though. Even if it looks really nice.

As much as I love Notion, things that you’ve mention really holding from moving sensitive data into Notion. Wish they had more solid approach to security.

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.

Yep, I’ve been forcing myself to use Notion more. It’s such a great tool for taking notes and such.

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.)

can recommend, it makes it so easy to start knowledge sharing. you’ll have to implement some rules after a while, otherwise it becomes victim of its ease of creating new content

For work use I haven’t found a good system. For personal use, I do the following:

– Sublime for very quick temp text files.

– Apple Notes for quick notes or for non-health related notes.

– TiddlyWiki for health tracking and identity tracking (e.g. what I value in life). Note: it’s a bit unconventional to do questionnaires in TiddlyWiki, but it can be done quite well. Especially now that I know how their plugin ecosystem works and can extend the system with JavaScript. I’m happy to share my template.

– BoostNotes for coding snippet.

Mediawiki works quite well. Most people use Wikipedia, so are able to quickly learn & use Mediawiki. Wikimedia Foundation has a number of initiatives to increase the diversity of Wikipedia contributors, so that translates into features non-technical people in your org will appreciate.

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.

Over the years, I’ve tried everything from MediaWiki, Evernote, OneNote, Confluence to Google Docs. Each seems awesome when you start out, but after a while, the novelty wears off and out-of-date crud starts accumulating.

The only thing that has remained constant for me are text files. I use two forms: if it’s related to a component I’m developing, I tend to place it in the repository itself, in README.md, or docs/.md. Other stuff I keep in text (.md) files in a Dropbox.

Only those things that don’t fit well into the above two formats go into Confluence.

Privately it’s org-mode all the way.

At work it’s a mixture of mostly Confluence and Markdown README files.

We’re the same.

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.

For our support team of 5 we just started using a custom text expansion tool I built in Electron. The snippets (canned messages) are stored in a WordPress site (we already have the main website / docs in wp so it was a good fit) and we all contribute to them.

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

I put everything in trello. It’s terrible as trello’s search sucks. But I still do it.

At work I just made a huge organization overhaul. Previously, the entire state of a project was scattered throughout some markdown files in an absurdly complex git repository, a gitlab wiki and a stash of hand-written notes.

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.

Have you thought about having markdowns rendered to a Confluence page? And maybe Confluence edits could get rendered back to git.

For the first use case, there are libraries available that sync your .md to Confluence which you could add to your CI system.

I use http://diigo.com to quickly bookmark/tag/annotate links I find. It is about the most advanced bookmark manager out there with capabilities to store copy of page/pdf with annotations, search content etc.

I second the needing a single, searchable source of truth. One of the main needs is for it to be maintained and updated. Having it all in one place helps with that and reduces the cognitive load of making the decision of where to update.

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.

I try to use Jira whenever I can. It sucks. But the thing is everything else also suck so for me Jira sucks a little bit less.

Apart from being pretty slow, I don’t think Jira really sucks once a) it is configured to your needs b) you know how to use it (which should be fairly easy with a in place). Which goes for pretty much any tool more complicated than notepad, so to speak: it’s not like the other similar tools out there are much better, just different, imo. Though I have the impression a lot of people who think Jira sucks might be using it where they actually don’t need it because much simpler tools could suffice in their particular situation.

All tools suck in a way that actual reality of doing work is complicated and tools are obviously way simpler so you end up trying to reduce the reality to fit the model of a particular tool.

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.

Sharing knowledge is tough; I don’t think there’s a silver bullet and everyone wishes they could do it better. Some strategies we use:
– Mailing Lists – a collection of mailing lists people can subscribe to if they’re interested in a topic. Bonus points if you dedupe messages, as it’s kind of annoying to get the same message more than once. We BCC to avoid Reply-to-All discussions/arguments.
– Discussion board – discourse…
– Q&A – stack exchange like Q&A
– Cross-team focus groups – these come in many flavours from “group level” (several teams sharing a common manager) to company wide. Some organise meetups/presentations that are really popular.

I’d encourage “all” of the above in some flavour or another, as people learn and teach differently.

Mailing lists is a trap. As your company grows it implements a data retention policy and poof, there goes all your knowledge when your old emails are auto-deleted.

Only use mailing lists for notification with links to the actual knowledge in a real document.

I use an outliner called Dynalist.

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 🙂

Another alternative is TreeSheets (http://strlen.com/treesheets/) which is desktop only but very fast and nice implementation of structured note taking tool. It’s very well suited as replacement for mind maps, categorization of items and mapping hierarchical structures. I prefer it to any online solution because of speed and data ownership.

At work, I use Confluence to log and share knowledge and I also ask others to do the same.
Over a period of time, this has worked wonders.

Personal organization:

(1) Use the Windows file system to create a directory (“folder”) tree that is often a taxonomic hierarchy. Have some good little command line tree walking commands.

(2) Do a lot with just text in simple text files. Generally prefer just simple text. Manage these files with a really good text editor. Have a lot of macros for the editor. E.g., start each entry in a file with a time, date, day of week stamp from a macro — good to have to document the entry even if don’t have much more.

(3) In each directory, have a text file that describes the other files or directories in that directory.

(4) Have a file, I call FACTS, just a text file, that has little facts: Each entry starts with a delimiter line, then a time-date line, then a line of keywords, and then the entry. The entries have user IDs, passwords, credit card info, e-mail addresses, USPS addresses, phone numbers, URLs of interesting Web locations, names of people and/or notes on them, etc. really just lots of short facts. Write a little editor macro to do search keywords.

E.g., since this thread likely has better ideas than I have, I put the URL of this thread in FACTS!

Big point: A single file of a few million characters searches essentially instantly and can hold lots of facts per day for years!

(5) For more, that is, for more serious information, knowledge, etc., write notes, even nice papers in D. Knuth’s TeX and index them in FACTS, describe them in the documentation file of directory of the paper, etc.

For what to share with others, I’d suggest relatively well written notes or papers. For more, have a directory, make a ZIP file of the whole directory, and share that. For more, maybe use GITHUB or some such.



https://news.ycombinator.com/item?id=21310030