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

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 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, recognize 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.

I am starting a new venture and will use BookStackApp (https://www.bookstackapp.com) as my single source of

It is searchable, offers markdown and WYSIWYG editing, page templates, and is quite opinionated on how to layout things.

My reasoning for this is to layout basic templates and processes for sales, support, ops, and office management.

This is also used to lay a foundation for ISO 27001 / (compliance and certification along with Eramba)https://eramba.org)

The last part is really niche, but coming from a Healthcare background taught me hard lessons in NOT HAVING YOUR DOCUMENTATION AND COMPLIANCE SHIT TOGETHER (TM) when you get vendor or compliance audits.

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.

I do this too. I use Sublime text in distraction free mode with a git plugin so I can easily commit / push changes.

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.

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

Do you use any specific structure for your markdown documents? Confluence i believe helps structure the knowledge

I use our own product (Asana –http://asana.com) to coordinate all our work and it’s also become a library and “brain” for everything that’s happened. Personally I also use and love Dropbox Paper (http : //paper.dropbox.com) for more long-form or ongoing research on topics both professionally and personally (I create a doc that I’ll work on for a long time and can easily part it and come back to it, even share it with other people etc).

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

Your audience should post the content about the screenshare session. The point of the screenshare is to share information. Your audience confirms receipt of that information by posting about the session.

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.

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.

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.

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.

Hi,

To organize and share our knowledge at work, we use the project management tool we developed:https://en.beesbusy.com

We create projects and tasks for specific topics and use comments for updates. And for more complete information, we can add a link to shared documents or an attachment. For instance, we created processes templates that can be updated and duplicated.

I find it very useful because knowledge is then organized in a workflow perspective: for instance, our product roadmap information is updated by everyone on a daily basis.

Since Beesbusy can be used for any type of project and has a mobile app, I also use it to organize my personal life. I share projects with my wife (shopping list, travel plans and so on) and I have everything in one place.

I would also recommend using a wiki for in-depth information. We use the Gitlab wiki for its simplicity, and we add links to its pages from our Beesbusy tasks.

Seconding TiddlyWiki.

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: 350 px

This looks particularly well when occupying one half of a wide screen.

Appearance – Code Foreground was changed to # 0a 5701 (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

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.

Mostly meetings and word of mouth. That’s why I lose one week on a lab software that I cannot make run on my local development machine. Even personal projects I spend a few months on are better documented than the software that is used here in production.

I use google keep for writing notes. In work we use the enterprise garbage all others use too. Google calender for datespecific stuff. Anything coding specific i have in github as markdown documents, some remain as drafts in my blog repository.

I’ve been really enjoying Notion. I used to use evernote and apple notes. Apple notes is still so much faster for quick stuff. But for writing / thinking / capturing etc. I’m in the notion camp.

Putting all your company 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 mentioned 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 organizing 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

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

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 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 (eg 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 .

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

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

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

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 flavors from “group level” (several teams sharing a common manager) to company wide. Some organization meetups / presentations that are really popular.

I’d encourage “all” of the above in some flavor 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 usehttp://diigo.comto 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.

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.

We tried. It’s pretty much like the normal stack overflow (Question and Answer based).

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

Personal organization:

(1) Use the Windows file system to create a directory (“folder”) tree that is often ataxonomic hierarchy. Have some good little command linetree walkingcommands.

(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. Eg, 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 littlefacts: 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 shortfacts. Write a little editor macro to do search keywords.

Eg, 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.

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.

EDIT: Check OPs history, he asked this exact same question 46 days ago!

Ive never heard of this startup before, now they’re all over this thread. Do you reckon they made this whole thread for marketing purposes? OP is a pretty anonymous user.

I already dislike them now & hopefully never have to use them. Someone else posted Tiddlywiki which is an amazing open-source program, suggest everyone at least check it out. It changed my life. I obviously have no stake in it, so why doubt me? No disclaimer necessary.

They’ve been around for a few years, and really are a pretty good collaborative tool with a lot of possible workflows and use-cases.

I’ve seen Notion mentioned often on HN, and after giving it a try I’d recommend to at least look into it to see for yourself.

Tiddly Wiki is indeed awesome. There is one few feature I would like (export to a graph database), and the wiki syntax is something annoying to use but overall this is genious level idea and great execution.

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

Notion is great – the most important thing to my mind is that it’s easy to find information later (by navigation, rather than search. The search UX is … not great). I use Notion to record everything that doesn’t belong in git, but still needs a canonical place to live.

>- Mobile performance could be better.

This is the reason I still use Evernote on mobile, even though I pay for Notion. Sometimes I’ll even bend Trello into a note-taking shape. eugh. The startup time is far too long for the short interactions that you have on mobile.

There’s one other shortcoming that drives me back to text files on a regular basis: often after highlighting some text in the desktop app, Ctrl-C doesn’t copy. This is absolutely infuriating when using notion’s code boxes to write down sequences of terminal commands. There’s no way of knowing whether a Ctrl-C succeeded or not until I’m pasting the wrong command in a terminal. Text files, with any editor is a much more pleasant experience.

Even though this sounds like a list of gripes, I’ve found Notion invaluable as a knowledge base.

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, and importantly your app startup time is very slow (which you already called out)

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