3 ms·
I really don't have any good recommendations, because I've never seen this done well. Never. In small or big companies. The two biggest challenges I've seen ov
by gorbachev 7y ago
I really don't have any good recommendations, because I've never seen this done well. Never. In small or big companies.
The two biggest challenges I've seen over and over again are:
1. People don't document changes well. You end up with pages and pages of outdated documentation describing things as they were years ago. This is especially hard on companies that have multiple teams using same underlying platforms/frameworks/libraries. Each team is going to create documentation on how they're using it when they do the work. Once the underlying technology does a version change / incompatible change, all of that documentation becomes obsolete but remains in the knowledge bank polluting the search results. I've become convinced this is an unsolvable problem.
2. Search. I have never seen a documentation system that gets me the information I need easily. It's closely tied to the problems described on the previous issue, but also almost all search systems I've seen are really bad at identifying the authoritative sources of documentation and pointing you to them as the first result.
Also think of your audience. The best documentation I've seen clearly separates documentation intended for maintainers of the code and users of the code.