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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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?
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.
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.
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.
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.
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.
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.
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...
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.
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.
> 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).
"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.
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.
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.
> 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.
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 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.
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.
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?
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.
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.
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!"
Daniel,
"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."
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.
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.
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.
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.
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 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
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.
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!).
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.
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.
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?
109 comments
[ 2.7 ms ] story [ 175 ms ] thread(Disclaimer / I worked there in the past)
There's no Linux download, no github, and especially, no server - I stay away from products like that, sorry.
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.
https://www.notion.so/Export-to-PDF-or-markdown-5406d98f17d2...
However, I work at a large company that has adopted Confluence, so I'm stuck with that for organizational knowledge.
The lack of an Android client might be a blocker, although according to their Twitter, one is only weeks away.
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."
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.
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.)
https://en.wikipedia.org/wiki/Knowledge_management
Also related is the field of "Organizational Learning".
https://en.wikipedia.org/wiki/Organizational_learning
It's a huge topic, and would be hard to do justice to in a HN post.
There are a lot of good books on the topic. A few I'd recommend include:
https://www.amazon.com/Handbook-Organizational-Learning-Know...
https://www.amazon.com/Wellsprings-Knowledge-Building-Sustai...
https://www.amazon.com/Winning-Knowledge-Transfer-Michael-En...
https://www.amazon.com/Only-Knew-What-Know-Knowledge/dp/1451...
https://www.amazon.com/New-Edge-Knowledge-Management-Changin...
https://www.amazon.com/Fifth-Discipline-Practice-Learning-Or...
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.
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...
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.
Wow. Every line.
There is such a thing as too many comments or too liberal use of comments in code.
For most code it will be overkill but there are some companies where it's integral for core systems.
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.
I would love to work in a place where documentation was cosidered a valuable asset, but I think that your example is off mark.
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.
on the other hand, if it was named something like number_of_records it would be clearer.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
[1]: https://about.gitlab.com/handbook/resellers/
If you don't have a librarian at hand try something that forces more structure at you.
https://leanpub.com/info-ops
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.
Best of luck with the book!
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!"
Daniel,
"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."
its honestly a market i dont understand, i'd love a high level primer on it.
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.
I've seen companies using forums, Google docs, and even Github repos.
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.
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
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)
Very much still working on it :)
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!).
Edit: I see https://news.ycombinator.com/item?id=16476388
[1] https://www.atlassian.com/software/confluence
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.
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.
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...
I just wanted to give a shout out to all of you and say thanks for giving so much back to the community.