Hacker News new | past | comments | ask | show | jobs | submit login
Ask HN: Organizing company knowledge?
190 points by tmaly on Apr 11, 2018 | hide | past | web | favorite | 106 comments
In the world of collaborative systems and wikis, what are some good resources for learning how to organize and structure knowledge at a company level?

I've found that the tool doesn't matter as much as the company culture. You need to foster a culture of documentation for EVERYTHING. It doesn't matter if you have the best tools in the world if nobody uses them.

Too often this falls by the wayside because documentation of processes and preserving institutional knowledge, while extremely important, isn't the type of work that gets recognized or rewarded.

If anyone can recommend a good way to align incentives here, I'd be very interested.

That is so right.

In fact one of the best organization I ever lived was in a small company (<30 employees) and everything was just organized in folders. Just Folders, no special tool, no wiki, nothing. In fact the main document describing the organization was maybe 10 pages long and the first thing you had to read when joining. As everyone was following it it made finding anything a breeze.

There was basically a semantic document number indicating what the document was about, which revision it was and where it was stored. Each Project/Product had an index linking to the document that was maintained by hand. This even extended to software versions where you had to publish some zipped version of your software at each release.

I wonder however how it would scale...

Agreed. I've long felt that the most effective tool is good curation of the material. You can use a wiki, or folders; I've used both successfully. The most important thing is that the material is organized in a way which allows for findings things efficiently. It can work if everyone knows the rules of said curation, but I've found it works best when one or two individuals are effectively the mods. The mods set the rules (folder naming conventions, hierarchy, maybe leave a README file in the root folder, etc...). If you use a wiki, you still have "folders", and the same rules apply. Otherwise, it becomes a big ball of documentation mud.

Would the mods also enforce said rules? Would everything has to go through them? Or do they just check that they are followed? What happens with what is not conform?

If managers don't reward documentation, people won't do it. There's no magic "incentive alignment" wand, managers will either think of long term and reward maintenance work too, or will only reward shiny new work. You need topdown focus on long term sustainability of organization.

In most corporate cultures not only is documentation not rewarded, problems caused by a lack of or poor quality documentation are usually not recognized.

It's worse than that - if you don't properly document stuff, you are that awesome guy who can help everybody. Sometimes I have the impression that some people to (semi-)intentionally create tons of already-out-of-date and misleading "documentation" to create the illusion that they did their job, but that's just the natural state of documentation is - hopelessly out-of date.

Well, maybe documenting everything is good, but what's more important is to make sure that the documentation is properly organized, which is exactly what OP is asking about. I've seen many wikis/confluences with multiple documents per topic, i.e. the author of the second document didn't know that the first one existed at all. In such cases, company wikis get cumbersome as they are polluted with knowledge.

I would say that the culture + making sure your projects and teams are well organized is the key to success. In addition, I'd recommend to follow some protocol when documenting things. This will make both writing and reading a less intense and more predictable task, resulting to a better overall experience.

Only for the sake of emphasizing your point, I have seen companies go out of business only because they did not follow proper documentation procedures.

Whats funny, is you must also be careful what you document as it becomes discoverable. Even procedures, especially when they are safety sensitive, involve the public, or anything sorbanes.

That's a nice suggestion, but I don't get what is meant by "sorbanes"? Are you referring to Sarbanes–Oxley Act of 2002?

This cannot be stressed enough. Often I see managers talk about Sharepoint or some wiki type tool within the company but then the culture of documentation is missing.

The best case scenario I found was in a bank. Each line of code was documented and rationale explained in plain english. This way hypothetically even a newbie could run the system.

While different places have different issues, I found that the quality of documentation was inversely proportional to people's insecurity about their job. More insecure they were about their job. More resistance to documentation was found.

> Each line of code was documented

Wow. Every line.

There is such a thing as too many comments or too liberal use of comments in code.

My bad, I should have been clearer. What I meant to say is each block of code was documented. So a logic change wasn't accompanied by line by line commenting rather a block comment explaining who, what, why and when of the change. The commenting guidelines were well defined too.

I doubt they meant literally every line, but for some of the more esoteric systems an average of one line of comment for line of code could be worthwhile. Paragraph of explanation, paragraph of code. I'm thinking of things like assembler or COBOL here.

APL/J are highly compressed and any reasonable explanation would require more than one line of documentation per line of code. I know there's some J in financial institutions.

Not if the system fails on a Monday morning at 3am after 20 years without issues and needs to be fixed before the business opens. Having comments for every line helps fixing it dramatically.

For most code it will be overkill but there are some companies where it's integral for core systems.

Honestly, these kind of problems are often due to unplanned/unexpected events (disk full, wrong permissions on a folder, OS updates correcting old bugs you have coded around) where having line-by-line comments would not help much if at all.

I would love to work in a place where documentation was cosidered a valuable asset, but I think that your example is off mark.

Sure but every line? You increment a loop counter, i+=1; and you say that in a comment?

The best rule of thumb is, make the code so clear that it is itself a comment, and only if the code cannot relay the meaning, then add a comment.

Depending on the code, it can be freaking hard to track down what that 'i' means, especially when someone writes a coding standard (or a language) where it requires all variables to be defined at the beginning of the function instead of close to location of use.

on the other hand, if it was named something like number_of_records it would be clearer.

> Having comments for every line helps fixing it dramatically.

That’s only true if comments are kept up-to-date. More often than not, they get out of sync with the code itself, causing even more confusion.

In my experience, in IT not software dev, you need mgmt to buy in that those hours are worth it and that they need to build those hours into everyday.

Can be sold as an on-boarding tool if you are in a large team some moderate turn over. Or as an insurance policy if you have a very small team with a few key team members, if we lost them for any reason would be a substantial setback to productivity.

In general I think people like good docs but fail to think about how to get there. Time must be spent.

I've seen MediaWikia and Confluence used successfully. It does require culture . . . but I've noticed that more people use the friendlier tool and that we have a lot more documentation with Confluence. The MediaWiki stuff was okay, but clumsy.

Other tools I've seen used with success generally have the characteristics of being lightweight, not too complicated, and having a relatively frictionless interface for making small changes (e.g., "press an Edit button and start typing").

I've been in a culture that desperately wanted to do documentation, but the tool that management forced people to use was SharePoint, and it was horrible (search functionality that never worked, very bad response time, very difficult to link or move documents, and worst of all a policy to delete "unused" SharePoint sites after a while . . . the result being that important engineering documentation was irretrievably destroyed). PMs loved the busywork that SharePoint created for them. I wound up putting all of our documentation into source control and snapshotting it to SharePoint periodically. This made me unpopular with the PMs, but I'm pretty sure the documents are still there, a decade later.

So tooling doesn't matter, unless the tooling stinks badly enough.

Yes, 100% this. It doesn't matter how good the tool is (and so many knowledge-management tools are not good), you need the processes and organizational habits in place to make knowledge management a success.

Effective knowledge management practices are something we think about a lot at Spoke (https://www.askspoke.com). We've studied other companies' practices and have come up with some organizing practices/principles:

1. Adopt the right tools: - Adopt cloud-based knowledge management tools that are simple to use. If new tools are overly complex, no one will use them. - Find solutions integrate with the applications employees are already using. (Be where employees already are, like Slack.) - A central source of information is best. If knowledge is spread across multiple tools, it will still be difficult for people to find.

2. Take advantage of new technologies: - Adopt tools and technologies that use AI to process and catalog resources. Ideal solutions may automate the processes of updating knowledge and/or automatically categorize and tag new content to make it easier to find. - Look for tools that use machine learning to improve as data is collected. Machine-learning technologies learn how people search for certain types of information, getting better over time at helping users find the exact information they’re looking for.

3. Document important processes: - Set aside time once a month for employees to create documentation on the tasks they’re responsible for. - Save all documentation on the cloud or some other shared server so everyone has access to it and to prevent document loss.

4. Find creative ways for employees to share tacit knowledge: - Establish a mentor program that pairs new hires with long-time employees. - Make sure managers know how to perform the most critical tasks that their teams are responsible for. - Set aside time for employees in related roles to cross-train. This will expand institutional knowledge, provide a source of backup when employees take time off, and reduce the likelihood of total knowledge loss caused by unexpected turnover.

So true. It also helps to have at least one person that feels ownership towards the knowledge management subject and it's systems (and builds up that culture, you're talking about). The best systems won't work well if there's nobody who puts thought into it and continually works on improving or "gardening" the knowledge system.

"I've found that the tool doesn't matter as much as the company culture. "

I think the tool choice doesn't matter much but having a well defined tool or process helps a lot. In my company it's never clear where to our documentation or where to find it. So every time you have to think about this and often don't get started . In my team we have started using OneNote for everything and now we always know where to put things and where to find them. Suddenly documentation is getting better and is actually useful because you can find what you need.

Previously we used SharePoint and data just went into it and disappeared to never be seen again. Totally useless.

> If anyone can recommend a good way to align incentives here, I'd be very interested.

My quick answer which may sound trite is compensation. An organization can compensate the author(s) either during their employment or even after. Yes, after. Award either non-voting shares. Set up a micropay system for each time a current employee "votes" the documented solution.

Documentation (and organization of documentation) is my thing. I hear so much talk and see so little progress. The most expensive work hour is the unbillable hour yet organization after organization continue with status quo of inaction.

> If anyone can recommend a good way to align incentives here

The motivation is simple, the implementation is more difficult.

People will document things if they feel as though they derive a personal (read -> personal, not party) and immediate benefit from doing so. That's it.

This is why getting motivated to doing unit tests is so difficult. There are many long term and group benefits, but the immediate and personal benefits are limited (especially in relation to the amount of effort).

Company culture is indeed paramount. In a previous career in Japan, I played a role in publishing a book on this very topic: "The Knowledge-Creating Company", by Ikujiro Nonaka and Hirotaka Takeuchi. Might be worth a read. https://global.oup.com/academic/product/the-knowledge-creati...

Ours is here: about.gitlab.com/handbook - it's open source: gitlab.com/gitlab-com/www-gitlab-com/

My tips:

1. Maintain a clear single source of truth

2. Make sure everyone can contribute to it. We do this by requiring at least to edits to the handbook during onboarding

3. Embrace it as an organisation: if not everyone is committed to it, it's hard to maintain it as truth

4. Constantly iterate and improve it. Structure is highly dependent on the content.

I think point 2 is really important. I've worked with a lot of new hires, especially college interns, and some of them are deathly afraid of coming in on the first day and messing something up. I always put together a getting started page on whatever wiki we happen to be using that details how to get the development environment up and running on the first day. Since the development environment changes as our code matures (new libraries to build against, new repos to check out, etc) following the wiki never seems to just work for someone unfamiliar with the dev environment and they encounter problems or just have questions. Whenever someone has a problem or a question the solution should be documented in the wiki, so we have the new hire update the getting started wiki as they go along. This gets them a little more comfortable making changes (since they see the whole building didn't burn to the ground after making a wiki update) and gets them in the process of documenting any problems or questions.

Curious whether you really mean _everyone_ -- including non-technical roles like Sales? I notice that for instance Sales seems reasonably well document [1] so, maybe so?

[1]: https://about.gitlab.com/handbook/resellers/

Yes, everyone == every single person employed by GitLab Inc.

wow that's great. How do non technical people can update it? Do you teach them Git?

Exactly. Or at least teach them to use GitLab, which is a good motivator to make the product easy to use.

At Airbnb we built and open sourced our own solution for this called KnowledgeRepo. You can find it here: https://github.com/airbnb/knowledge-repo

it is used throughout the data org and has been extremely popular and useful. there is a blog post here with more information: https://medium.com/airbnb-engineering/scaling-knowledge-at-a...

Airbnb has been an incredibly good member of the open source community. Airflow is a great tool, and this tool looks really good as well. I was just digging around looking at superset a while back, and that looks awesome as well along with Flask App Builder.

I just wanted to give a shout out to all of you and say thanks for giving so much back to the community.

I really like Knowledge Repo but I'm not sure it solves the same problem. It seems more like an internal publishing system for results from data science not a way to document and share arbitrary company knowledge. Have I misunderstood the project?

I believe the general field of how you structure information is called "Information Architecture" - https://en.wikipedia.org/wiki/Information_architecture should provide some starting point, as will searching Amazon for books on the subject.

There are other strands of thought that may also be relevant. E.g. I think HR people often think about "workspace learning" or "training and development" (e.g. https://en.wikipedia.org/wiki/Association_for_Talent_Develop...).

And in the world of management there's the concept of a "learning organization": https://en.wikipedia.org/wiki/Learning_organization

(You will get a lot of answers involving tools. Tools are the last thing to think about.)

Oooh, nice. Thanks for the detailed recommendations!

One trick I've used successfully, at least at the team evel, is to maintain a "doc of docs".

This is a document which exists to link to other documents. I use a shared Google Doc for it (which is almost equivalent to a wiki).

Since it's a document (and not a folder or a spreadsheet) each linked document can be combined with some explanatory context - is the document current? What does it cover? etc.

I also like splitting my doc-of-docs into different headings, for example:



Related projects from other teams

The key benefit of the doc-of-docs approach is that the answer to EVERY question about "where can I find documentation for X" is "Look in the doc-of-docs". And the follow-up answer if they don't find it there is "Go and find that document, then add it to the doc-of-docs".

Try https://www.notion.so! It combines docs, wikis, and todos; it's collaborative, and it's beautifully designed. It's perfect for building knowledge bases for teams.

(Disclaimer / I worked there in the past)

At a glance, it looks like a product that's stored on the company's servers. Why would any company, startup or dinosaur, want to put their knowledge base and documentation in the hand of a new pretty and fancy product that might fold next month?

There's no Linux download, no github, and especially, no server - I stay away from products like that, sorry.

> Why would any company

Almost every company uses external services for this sort of thing right now. Google Drive, Confluence, whatever. Notion allows you to export to PDF/Markdown as well.


Confluence and a lot of other products allow the company to install the product on their company server. Not on the server of some "startup". A lot of industries does not allow you to just store think on Google Drive, think any industry working with sensitive information like healthcare and the defense industry.

Whilst integration with existing/other tools would be a massive insurance feature and a pretty nice feature all the same, I think it's a bit unfair to rule it out of hand like that. Could it work for a big corporate that would generate a load of docs/need to import from whatever they have today? Maybe not. Could it work for a brand new 1-2 person band with a few bits and pieces? Probably.

You can export it as a HTML document, PDF or Markdown and do what ever you want with it.

So I would have to edit my documentation in this app, export to HTML and rsync the files to a web host on our intranet to share it? I'll stick with Mediawiki.

I can second the recommendation of notion. It's worked very well for my organization / productivity needs.

However, I work at a large company that has adopted Confluence, so I'm stuck with that for organizational knowledge.

Based on a quick look, notion appears to be a great fit for what I'm looking for.

The lack of an Android client might be a blocker, although according to their Twitter, one is only weeks away.

I second this. While it doesn't fit my own workflow (I am a heavy workflowy user). I think when you have to find a middle ground and a tool that everyone will have some pleasure using, Notion is a better one than most.

Not a direct answer, but I recently tried to get a documentation and organizational thing going. To start, I created a dictionary which contains all of the terms, topics, ideas, reports, systems, internal phrases, etc; basically anything and everything I could think of. It quickly grew to a double digit number of pages, and it was very useful for outlining everything I might want to document.

Now, documenting things is a different story...as gringoDan pointed out here (https://news.ycombinator.com/item?id=16811654), whether or not your documentation process/tooling gets anything done is directly 1-to-1 correlated with company culture on documentation. I've personally tried numerous times to get documentation going, and it always fails because no one keeps up with it.

I literally spent the last 2 weeks looking into this. Used Confluence and a few wiki solutions before. Both in context of a tech team in a large investment banking institution, startups and community organizations. In the end it was a close call between Confluence and a new product called Slab, for my small startup but we decided to go with Slab (http://slab.com).

What I liked about Slab is the way better performance over the Confluence, quick integrations from their team (took them about 2 days to add draw.io integration on request). I liked how clean it was and easy for non-devs in my team to understand the structure.

One thing that I've found to be helpful is to write automation scripts for core business processes. In particular scripts using the python library Fabric3 ends up very readable. It's like runnable docs...

How was machine X configured? --> read the setup script.

How do I import the CSV data from server Y? --> check the steps in the script.

How do I add a new user to system Z? --> check the steps in the script.

I once used Drupal 7[1] at a previous company. It worked out well. Its OSS so cost was my time, time which I would still have spent on a proprietary solution. Drupal has a concept of nodes, a node is a type of content. In our case, we were documenting a BI system. I created a node for reports, which were related to database table nodes and in turn had field nodes. It's amazing how much documentation can be associated with a single field. This included historical information why some values differed, the different apps writing to the field and sometimes legislation documents were attached to the field. I used the Feeds[2] module for automated data feeds. I had a script that exported Information Schema from our DWH. I would then import new fields that had been created. We would then edit the new field nodes. I used modules that provided syntax highlighting a module that notified users of new content. I was also able to write SQL queries against the database to extract documentation as data.

The point I am trying to make in case it isn't clear is that a system that comes with plugins and allows you to structure the documentation to suit your organisation is best.

As others have noted, not many developers love documentation. In my experience, it seems to happen in bursts. It's remarkable how useful and relevant a piece of information is even 5 years down the line. [1]https://www.drupal.org [2]https://www.drupal.org/project/feeds

We use a gnarly WordPress install with a user permissions plugin.

I hate it, but it is the only thing we've found that meets all of our needs, isn't $500/mo+, and gives our mid level managers control.

We use it for everything from on-boarding, to training, to system documentation, to competitive intelligence documentation.

Sure we could build something custom, but overall it works and it's given the team leaders control over their "domain."

Just curious: why WordPress and not a Wiki of some sort?

We had robust training/quizes setup on WordPress using gravity forms.

Also we found that making people specifically responsible for documenting their job/building training for others before they "moved up" into a higher role was really effective. Wikis didn't allow for the granular control we wanted over who got to see training/documentation.

My team hosts a meeting every two weeks to talk about staffing - who's overworked and why. We also discuss what problems we're dealing with and solutions we've found for those problems...so the group's knowledge grows, but not in an official, legible way. It's still tribal knowledge, but an effort is made to at least increase the size of the tribe.

The only time when people are absolutely required to document something is when it's a deliverable to a customer...so the customer needs to understand the product we're delivering to them.

We're all supposed to be using an engineering notebook to help document designs...but those really only come into play when someone leaves the company and the company is trying to retain as much IP as possible. Though they are incredible useful on an individual level.

Other than that, it really comes to down to finding time to draw a diagram or do a brain dump into a document describing how something works. Maintaining ICDs (Interface Control Documents) describing software/command protocols or hardware interfaces is pretty easy and provides a lot of information.

Team drive is a gsuite feature one found handy. It has to be turned on in older gsuites as it's a newer feature but it is on automatically in newer ones.

It is good for defining structure and permissions at an org level for files and folders and solves that pesky problem of documents not being accessible if the Creator of them has their account shut down.

Honestly there is so much software out there I have trouble telling what is good from bad. I was amazed that some one can start and bootstrap an indie company knowledge site (https://www.indiehackers.com/interview/generating-25-000-mo-...) since there's Confluence and Sitepoint and god knows what else (wikis are basically open source tho requires devs to integrate, you can always hack it with google drive and google docs, etc)

its honestly a market i dont understand, i'd love a high level primer on it.

In my experience, something that already ties into your company's authentication platform can really simplify access-control problems.

For example, when I worked at a company that used Google Apps for Business for everything, I set up our documentation in a Google Sites Wiki. Now that I'm working somewhere that uses Microsoft for everything, I've set up a Sharepoint wiki.

In both cases, the tools wouldn't have been my first choice from a page-editing or layout standpoint, but the ease with which my less-technical co-workers can search and find information and process documents with their existing credentials has been key to encouraging broader use.

Somewhat of an odd option, but we use Trello cards since we live in Trello anyway. Two of the most frequently used boards: a "Handbook" for employee matters and "Customer Knowledge" where we distill custdev and sales conversations into topic cards.

Just paste in new information into the comments section and then work it into the summary in the card description. You can also assign each topic to have an owner to make sure the card stays fresh.

When there's a much larger document, we create a card for it and link to a GSuite doc. For dev knowledge however, it's updated in our repos directly (e.g., README)

In that vein, I've tried to create something vaguely trello-esque but more geared toward knowledge management rather than project management: https://www.contabulo.com. Specifically, I think it's much nicer for longer articles/documents than what you would typically put in a "card" on Trello.

Very much still working on it :)

We've started using StackOverflow for Teams (https://stackoverflow.com/teams). It's really good, most of the company knows the experience pretty well already.

But, as others have pointed out, adding a tool won't create knowledge. You need to foster a culture of creating documentation, writing notes, just writing everything down. It's so easy to relax after a hard problem, but if you document it, then it will be easier in the future.

Very simply, you need at least one person to play curator. The curator maintains/publishes builds of the documentation and keeps everyone on task for docs. Even in medium-sized groups curation is not a full time job (usually this is a senior dev anyways, and they always have other stuff to do). The curator does not have to write everything, but they show up in the code reviews ask others for their docs and makes sure they are collated in a well structured and organized form.

Some other things I've learned... Wiki's suck, they become stale, they are disorganized, very informal. I recommend just keeping big ass user guides (can be different ones for different systems or even user guides about procedures that are not about products) using a well-organized documentation system and a well-kept table of contents. Don't waste tech writers on internal docs. They'll spend half their time asking the dev anyways, it will get stale, and asking a dev to write something is not asking too much. Keep the docs close to the code, but not in the code like comments. Docs close to the code can let people have less friction between code and doc commits. Each non-trivial repo should have a manual (a.k.a. user guide) anyways. And if you have to, say, grab a bunch of RST files from a few disparate Sphinx doc locations, so be it.

I personally use documentation as a point of pride. My favorite part of any project is documenting the awesomeness I did. I just make sure I order it in a reasonable order and don't bloviate.

We used wikis, it was a nightmare.

If you don't have a librarian at hand try something that forces more structure at you.

Yeah I've learned that organiztion of data seems to come back to librarians or libraries.

Use a Digital Asset Management (DAM) system. You get binary version control, automatic extraction of text for searching, automatic document type conversion, tagging, thumbnails, custom fields, etc. Everything can be sorted into a category hierarchy, with many-to-many relationships. You can control who can access what and when, and users can use native or web-based clients.

As others have said, your company culture has to support it, lest you use the resources to set it all up and no one uses it.

I'm working on something that aims to make this easier from a more ground-up perspective, but it is many years away from when we can say this problem has been solved completely. Here's something I've learnt in the process (as gringoDan said in a comment on this tread) company culture is the fundamental requirement. The limitation with organisation tools is that they amplify your company behaviour digitally.

If your company does not prioritise a written culture, then there is no tool that can come in and magically do it for you. Your tools will only amplify this phenomena (your team will use the tools for some time, and then quickly think of it as "another thing to do" when the shine wears off and stop using them)

This is because of the way current tools are set up. I have seen companies hire interns to help keep their internal knowledge updated. Despite this, there is always some document to update. I view updating documents as work that is required to keep other (perhaps more "important") work seamless. I can draw a comparison between maintaining internal documentation and writing unit tests (both equally important, while being underrated and easily postponed for later) At scale it either compounds to a technical debt and can bring the whole company to a halt momentarily.

I like Nuclino personally. Good feature set without all the cruft of a wiki solution.

For smaller windows-only companies I've recommended OneNote on a fileshare.

It is really simple, everyone who can use Word can use it. It is also very wiki-like in that it is quick to edit, searchable (and fast), versioned and it is easy to see when something has changed (bold tabs).

Personally I used to prefer dokuwiki (and before that I made a custom tool in Javascript to simplify use of mediawiki to document procedures.)

There have been a number of comment stating something like “the choice of tool doesn’t matter, the use of the tool and convention does”. However can anyone recommend a good tool?

We’ve been using a moin moin wiki. It’s ok, but we’d like to move to a simple, hostel solution so we don’t need to maintain a moin moin server.

We don’t need fancy, just simple with attachments, images and links.

This is exactly what we built Topicbox for!


Because large amounts of knowledge are locked away in individual emails, having a central storage repository with good search and easy control over the flood of information makes it possible to find the knowledge in-context later.

We have a monorepo. Many subdirectories have README.md files, plus things like godoc/pydoc/etc. We also have a top-level docs directory for stuff that doesn't fit anywhere else. All of this is compiled to a static HTML site during our builds and published to a spot we can all view/reference/link to it.

I've been at two major companies and both used some form of Wiki or collaborative site. If any company had a good idea how to do this, everyone would be doing it that way by now. There are definitely still improvements that need to be made to existing platforms. For example, neither site had a great search engine.

In addition to the right culture, great platforms enable great ecosystems. I have found that putting everything as Markdown on a collaboration platform like Github/GitLab works really well and enables collaboration in a number of ways:

- people don't feel awkward to modify other people's content because there is a collaboration and review process in the form of pull requests

- you can assign different people to oversee different parts of the knowledge base. They make sure the organization of the knowledge base doesn't get messed up by reviewing changes of other people to it.

- you can keep others in the loop about important updates (big and small) by tagging them in pull requests

- verification can be automated via bots and CI, for example using https://github.com/originate/text-runner

I have used MediaWiki for unstructured information with additional extensions for structured data (Semantic MediaWiki or Cargo) with Page Forms Extension.

This is difficult and time-consuming to setup. But if you cann afford the effort, this gives you a very flexible system where you can decide what to store in a structured or unstructured manner. Structured data can of course be queried, aggregated, vizualized etc. Together with the Page Forms extension this can replace many Excel Spreadsheets and MS Access solutions.

If you really know what you're doing, you can even do moderately complex CRUD Applications. But then you really need to know your way around several extensions and of course wikitext.

For simpler use-cases I've also used Drupal. For this use case it's not as flexible as MediaWiki, but you can do a lot through the GUI and build custom Forms / Views.

Collaborative learning is a situation in which two or more people learn or attempt to learn something together. Unlike individual learning, people engaged in collaborative learning capitalize on one another's resources and skills (asking one another for information, evaluating one another's ideas, monitoring one another's work, etc.). More specifically, collaborative learning is based on the model that knowledge can be created within a population where members actively interact by sharing experiences and take on asymmetry roles. https://www.besanttechnologies.com/training-courses/data-war...

Reinforcement, not organization is critical. Its simply not enough to make knowledge available. You have to reinforce and reward its use, contribution, sharing and security.

At my company I do internal nurture marketing (thank you MixMax) to remind employees to use knowledge resources, and to contribute to them.

Anything works as long as everyone does it.

I've seen companies using forums, Google docs, and even Github repos.

Every documentation system I've ever seen at any company -- large or small -- is almost always undermined by the inclination to: 1) not look things up, and 2) ask someone before looking things up.

The information is almost always 3 clicks away, but people just want to ask another person, or behave in a paralyzed manner as if the information couldn't possibly be found.

And if you work in a "lotta meetings" company culture, even moreso.

I'll rant a bit on the topic:

Starting out can be tough. Experience and observe the company/department/team you are seeking to organize and structure the knowledge for.

* Do they care about capturing, authoring, presenting and maintaining knowledge? How much do they care?

* Enough to insert steps into their existing processes or create new ones?

If so, you have a chance. Otherwise, focus on organizing and structuring YOUR OWN company knowledge. When others look over your shoulder at a meeting, read your notes, your reports, your guides, you may be able to entice.

Examples speak louder than words.

Tooling can be tough. If you work in a small outfit, you can likely spin up the best KM tools available. If you work for a dinosaur, good luck. They are likely already entrenched with some sharepoint mess that busily employs 10's if not 100's of people. Bringing your "new tool" to the IT department will get you the run around. (I've been trying to implement Gitbook (my fav KM tool) for over 1.5 yrs.).

Large companies may also have problems with cloud deployments. And honestly, in light of data breaches, etc, I get it. Many tools (most of the ones in this Ask HN) are cloud-based so this may limit your options.

I'm currently using OneNote to author and present ~300 pages of docs to ~3000 users. Being the SOLE author, this is fine. The style and structure are consistent, but I don't like it. OneNote doesn't support markdown (are you serious Microsoft?!? you don't have an f'ing markdown editor yet?), locks you up in a proprietary format, etc. etc.

Its also too "willy nilly". Its meant as more of a personal KM tool rather than a something for general consumption.

Where I lean:

* Static site generator under git version control

* Hook up with your local "Write the Docs" Meetup

* Check out the annual "Write the Docs" conference (coming up in a few weeks in Portland!)

* And start with YOUR OWN company knowledge.

We started using Slite http://slite.com/ 6 months ago with great success. We previously used Atlassian Confluence for our internal knowledge database, and it resulted in very static content and poor adoption. Slite is a much better choice: we use it for "static" company knowledge (like onboarding, processes, etc.), but also for most of our dynamic content (meeting notes, document drafting, sales support documentation, etc.).

Many people (including dev) use it on a daily basis, and most people on a weekly basis.

Definitely recommend.

For me this was an oddly-timed AskHN. I am publishing a book on this exact topic in the next week or so.


Could you tell us more about how your book is relevant to the topic at hand? I've tried to read up on information operations, albeit in a different context.

Sure. I wasn't looking to pump the book, it was just weird.

I have spent my career with technology teams, either 2 guys in a closet or 40-thousand people working on multi-year, multi-billion-dollar efforts.

Something weird happens between the 2-guys scenario and the 40k version: critical information stops moving around effectively. Many times big organizations seem to exist and profit more out of a sense of inertia than strategy.

Looking at this, over the last several years I've been trying to identify why some organizations do well in how they handle information flow and how some (most) organizations don't.

There is a ton of detail here. It encompasses everything from Lean Startup to Business Modeling and Extreme Programming. (Way too much for an HN comment, sadly!) There are a few folks talking about how to think about information at the meta level, but not a lot. Happy to point folks to some free online resources. Just let me know specifically what you're looking for.

I'm working on something in the same domain, and it's very interesting to speak to somebody who has approached this problem from a scientific angle. I will email you shortly with some queries, if you please.

Best of luck with the book!

Do you have a summary for it?

Build the right thing.

We spend so much time and effort on building-things-right. It's much more important to build the right thing. Usually (not always) boils down to information flow and feedback loops.

I'm so far in the weeds right now with the book publish date coming up it's for me to provide a good overview. Here are some comments from my alpha reader group (I do not know these people and they are not paid in any way for these recommendations)

Hey Daniel,

Got info about second part of Info-Ops, will get to the details later today. But I just wanted to give you quick info (while not very useful at this stage I assume, but still...) - few days ago I finished the book. I loved it. It's written in simple language, easy to understand and digest even for not-native speaker like myself. So that's very good.

The bad: I wish I read it two-three years ago, would make me much better software developer!"


"You know, when I first got to know you, I thought you were a funny guy, but arrogant. (Yes, I am aware of the irony.) After reading the beginning of this book, I realize you're not actually arrogant - just really fucking capable. This may be the best book about process analysis I've ever read. OK, I have to admit it may actually have been the only book about process analysis I've ever read, so there's an inherent grain of salt there, but damn. This stuff is truly fantastic. Very, very well-considered and thought-provoking. I am truly and unironically happy you've given me the opportunity to read it...Seriously, I find this roughly on par, in its level of thought-provocation, as Doug Hofstadter's work. I might have a slightly weird way of looking at it, so don't derive any expectation of universal acclaim from it, but I do mean it. Damn fine work."

"Daniel. Wow. I didn't know you had it in you. I'm eager to keep moving forward. ... I like your approach and wondering if you can or were at all all looking to at some point to speak/teach/consult on the topic? (We could use at current client!)"

"I'm Ola Ellnestam a software developer and team coach/lead. My job is to balance software development with regards to process, delivery and collaboration. I didn't know what to expect from Info-Ops, I thought it had to do with DevOps and information. A few chapters in though I realized it gives the reader a concrete way of looking at, understanding and in a way, manage the information that flows through a software development effort. It helped me understand underlying problems with that flow and how to deal them. It also gave me new ideas on how to work with semantics in software development in a more pragmatic way. If you want to know how to create a shared mental model in your team and beyond, read this book and I am sure you can become the grease between business and tech."

I set up an OpenGoo (now FengOffice) instance internally where I work many years ago. We use it to store Notes, categorized in Projects and Subprojects. The interface makes it easy enough for non-technical people to use it and search works well enough. There are also custom fields we've added to Notes, to make up checkboxes and dropdowns.

It's still our main point of truth for a lot of processes and details, though we've been considering moving to Phabricator which we're using for our code.

I´m the COO of Zenkit, a project management tool. But that´s not the point right now. On our Blog https://blog.zenkit.com we want to try to show people how to work effectively alone, in teams and remote. We also show how to use systems like Zenkit to organize every company level.

Confluence at my last job, it was a mess. If folks don't make an effort to keep documentation up to date & organized I doubt the tool used matters much. Finally find the stage db fqdn for that one app, but turns out it was moved twice in the year since the documentation was updated? Good times!

Make all of your company's internal technical discussions archived and searchable forever, no matter where they happen (mailing lists, bug tracker, code review, chat, etc). That's more helpful to me than any amount of deliberately written "documentation" that instantly goes stale.

Knowledge sharing will be effective when people get along well and care about what they do. I don't think the tools matter that much after that.

Create small teams that work well together, give them lots of responsibility and autonomy, and let them work on the things they really care about deeply.

My employer uses Confluence [1]. I'm not a fan of Jira but confluence is ok.

[1] https://www.atlassian.com/software/confluence

there are a few commercial knowledge-base software vendor.

to use open source, wiki is not structured and i really don't like that much, folder-files are hard to manage once you have many files.

CMS could be used(e.g. drupal), however I hope CMS can support markdown _natively_ which is not the case for now.

I have spent so much time to find ways to organize knowledge myself, to no avail, I use drupal 7 along the year, which is not great, but I could not find anything better.

This is what I've studied, and taught in informal unpaid and paid settings. A presentation with audience teamwork is my favorite method.

Slite.com (YCW18) serves exactly this purpose. Full disclaimer it's my company, but this is the core issue we are tackling.

2 classic pitfalls with knowledge are - what do you put in this word (for instance are meeting minutes "knowledge"?) - how static you think it should be

If you only envision knowledge as static processes, traditional wikis work. If you want all your team to contribute and for this knowledge base to be a daily used tool, with all the information that matter you need another setup and we are building Slite for this (happy to have feedback!).

What makes Slite superior-to or differentiated-from Notion?'

Edit: I see https://news.ycombinator.com/item?id=16476388

Evernote Business: https://evernote.com/business

Recently we started using Slinkky https://www.slinkky.com . It makes organizing information for your team and company really simple. There's a 30 day trial for startups so there's no loss if it doesn't work out. You can collaborate on personal boards with coworkers and add team spaces for shared content. You can restrict permission by user so only admins and managers can add content to team boards.

Never trust a website without an About page.

Ya we use Slinkky at my work too. Really good tool for organizing links with your team

Simple but powerful note taking: https://notein.com

I feel qualified to provide input here. Hopefully it helps. Ironically, it is quite verbose.

I position myself as

- Virtual Chief Knowledge Officer aas

- Virtual Chief Quality Officer aas

- Virtual Chief Information Officer aas


Issue 1: "Knowledge and process is seen as a dichotomy, but shouldn't be".

All businesses that I have worked with, and all discussions I have seen or been a part of, draw a distinction between actual operations, and the workflow & guides that govern them.

The problem manifests as such:

- The business doesn't update info, as it is buried away (out of sight, out of mind)

- This fundamentally undermines the information immediately, making it even less likely to be used

- The information is therefore less likely to be updated, compounding the issue further.

Instead, these should be tightly integrated. For example - If a ticket/job is generated, the relevant guide should be proactively attached by the system as part of that ticket. When a human comes to that job, the information is there waiting for them. People aren't going to go out of their way to bring up information.


Issue 2: "The Business Manual is verbose, not effective or up to date, and people don't like it"

Most business manual's aren't encouraging use anyway, in that they aren't relevant, are too constricting in areas, and are verbose.

1. Simplify (streamline the process, break the process down into procedures, break procedures down into atomic steps. Everyone in the organisation should know exactly what your processes are)

2. Automate (any steps that can be automated, should be)

3. Steer (Any steps that cannot be automated, should have a guide attached - But only to the extent that you need).

The last point is critical, as I often see strict, long instruction documents that stifle creativity, have a negative impact on job satisfaction, and don't cater for everything possible anyway.

Instead, guides should be curated to the extent required only, using the following attributes:

- Budget hours (if you exceed this let's regroup and decide whether to re-plan)

- Instructions (only where specific and accurate steps need to be followed)

- Considerations list (exhaust this before escalating, but allow creativity)

- Notes (general hints and tips / knowledge base that should be added to over time)

- Team (a section which shows who can train and undertake the task, and who is on the 'to-train' list)

- Reference (reference information or items)

- Tools (any potentially relevant tools)

This strikes a balance between paternalism and laissez-faire, and uses each where it is most effective. It solves a problem in that business manuals tend to be 'ineffectually authoritarian', so people resent them anyway.


Issue 3: Information gets stuck

The following should be standard practice (knowledge transfer is king):

1. An entity is generated in the system

2. Template auto attaches

3. The template has a list of people authorised to undertake that entity, and a list of people to induct to that procedure/task

4. One of those authorised people undertakes the task, along with someone on the 'to train' list

5. Repeat 1-5 until trainer can 'pass' trainee. Trainee's name added to the top of the authorised list

6. Trainer moves down the list of members as people are inducted and added to top of the list, therefore gets used less and less for that task and is freed up to move 'up the process chain'

This creates a moving machine within the organisation, where people are proactively provided information to complete their job, and proactively are able to pass that knowledge on and faciliate personal development within the company.


Issue 4: Reactive thinking, lack of proactive thinking

The following should be deeply ingrained into the culture:

1. The business becomes aware of 'the system' no longer comprehensively and accurately reflecting reality

2. The interface node (user / system) that discovers this difference should log it immediately in or as a system entity (service ticket, general client, technical documentation update, client information change, new client user, data breach, potential sale, etc.)

3. All relevant information should be auto-attached

4. Whenever any entity is being closed off, the team member considers whether there are any potential follow ups that they can derive (including improvements to the template/guide), and triggers them


"3 clicks away" is not good enough. "2 clicks away" [was never] good enough. Information needs to be a) in the user's immediate view along with their work, or b) a single click away (to hide peripheral information, so as not to overload the primary view).

Documentation is unfortunately often an afterthought, or at best is a follow-up task for a system that is not at the forefront of people's vision and mind.

As a final thought, here are two contributions to the suggested software so far (no affiliation):

- IT Glue (if you are in the IT industry) (www.itglue.com)

- Process Street (www.process.st)

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact