One inevitable thing working in tech is writing and reading Wiki. If your product depends on some other team’s products, you most likely will need to read other teams’ Wiki. But a lot of Wiki is hard to follow and loses focus easily among unimportant clutter.
One common pitfall is providing seemingly one-click solutions without explaining the nature of the stuff you offer. Too often we see words like “If you are an XYZ typed service just add ABC as your dependency and then DEF in your configuration file”. This seemingly fool proof guide decays over time as your product and your dependent product evolve, and eventually becomes so obsolete that it is useless. Another disadvantage is you will need to enumerate all types of customers, which is extremely hard if not impossible to achieve. Even if you can cover all types of use cases today, there are going to be emerging new use scenarios that you cannot keep up with. A much better approach is do not assume that your customers are fools and provide essential information with a few sample use cases (your tech colleagues are not that dumb after all). For instance, if you are a service provider, what is your endpoint and what network it belongs to; what is your protocol; how are you authenticating; what input data format do you expect and what data format do you return. Even if you only vend a client library which is super awesome and can hide such details underneath, you still should provide enough information that when your customers’ execution environment changes and things don’t work as expected, they know what the issue could be; and when your vended software have bugs, which is 100% guaranteed, your customer can pinpoint it quickly without having to waste time on debugging for you.
Another disappointing thing is offering too little information in the Wiki body, but adding lengthy FAQs. For sure, addendums are hard to avoid when you are describing complex things. But adding a disproportionately large FAQ section reflects that you cannot write logically to teach your audience in a heuristic manner. Some FAQs, hilariously, contain questions such as “why we built this thing” and “what are the key parameters of our product”, which should belong to the overview or introduction in the first place. Finding valuable information in long FAQs is a game of chance. If there is highly valuable information in the FAQ section they probably better belong somewhere else in the Wiki body; other less critical information that lies in FAQs should be able to be safely omitted without negatively impacting understanding of your product. I often see intimidating FAQ sections that contain over 100 questions, and the only way I can make use of it is searching a keyword with an exact match. If I cannot find such a match, I close the browser tab with a sigh.
A third type of bummer is poorly maintained Wiki. We often hear the doctrine that “whoever reads the Wiki and finds inaccurate and outdated information should update it”, which is good intent but practically causes the Wiki to deteriorate over time if no regular maintenance is applied. Crowd-sourcing based Wiki is error prone because it is seldom peer reviewed, and chaotic in style because a lot of people don’t check if their newly added one-liner is coherent with the rest of the content. Wiki should be an authoritative source of information, so it needs to be constantly audited, improved and sometimes completely refactored, by a designated owner.
With all above being said, I certainly acknowledge that writing high quality Wiki in the tech industry is very hard. Things we document mutate quickly and we are all busy. Devoting time in writing internal Wiki takes a lot of effort but often receives little credit from management. But from a strategic perspective, there should be no excuse for under-investing into this type of task. Keeping your internal documentation as good as your external documentation would save a lot of wasted effort and greatly improve your teams’ productivity.