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