6 ms·

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 h

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.

itamarst 9y ago
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.
- crdoconnor 9y ago
  In most corporate cultures not only is documentation not rewarded, problems caused by a lack of or poor quality documentation are usually not recognized.
  - virgilp 9y ago
    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.
ericst 9y ago
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...
- daveslash 9y ago
  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.
  - ericst 9y ago
    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?
thisisit 9y ago
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.
- hellofunk 9y ago
  > 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.
  - dx034 9y ago
    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.
    - methyl 9y ago
      > 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.
    - Pamar 9y ago
      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.
    - 9y ago
Fannon 9y ago
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.
justinmayer 9y ago
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-creating-company-9780195092691 https://global.oup.com/academic/product/the-knowledge-creati...
benjlang 9y ago
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 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.
nemacol 9y ago
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.
mbesto 9y ago
> 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).
maxxxxx 9y ago
"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.
andreygrehov 9y ago
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.
- godelmachine 9y ago
  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.
  - SeaDude 9y ago
    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.
    - godelmachine 9y ago
      That's a nice suggestion, but I don't get what is meant by "sorbanes"? Are you referring to Sarbanes–Oxley Act of 2002?
kabdib 9y ago
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.
wannabetechba 9y ago
> 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.

itamarst 9y ago

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.

crdoconnor 9y ago
In most corporate cultures not only is documentation not rewarded, problems caused by a lack of or poor quality documentation are usually not recognized.
- virgilp 9y ago
  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.

ericst 9y ago

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

daveslash 9y ago
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.
- ericst 9y ago
  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?

thisisit 9y ago

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.

hellofunk 9y ago
> 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.
- dx034 9y ago
  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.
  - methyl 9y ago
    > 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.
  - Pamar 9y ago
    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.
  - 9y ago

Fannon 9y ago

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.

justinmayer 9y ago

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-creating-company-9780195092691 https://global.oup.com/academic/product/the-knowledge-creati...

benjlang 9y ago

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

nemacol 9y ago

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.

mbesto 9y ago

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

maxxxxx 9y ago

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

andreygrehov 9y ago

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.

godelmachine 9y ago
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.
- SeaDude 9y ago
  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.
  - godelmachine 9y ago
    That's a nice suggestion, but I don't get what is meant by "sorbanes"? Are you referring to Sarbanes–Oxley Act of 2002?

kabdib 9y ago

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.

wannabetechba 9y ago

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