MediaWiki's cryptic documentation
Documentation is a strange thing. Even the initial design documentation serves all manner of purposes - whether to help sort out what an idea even is, to sell the idea to clients, to lay out a general basis of just what to develop, or even to reassure or scare away users. Depending on the initial purpose for which it was written, it often winds up unclear to those trying to follow it later, or to those outside the target audience.
Or so I assume. I'm not sure why, but MediaWiki seems to have particularly cryptic documentation, at least in the design department, which is often quite difficult for users in particular to follow. Now this can be useful - if they don't know what something is supposed to be, they can't very well complain about it - but on it can also be problematic because it tends to result in concern. What is this thing here? What are these words for? Is this new thing Q supposed to replace thing A, be thing B, complement thing C, or have nothing to do with any of the above? And since it is so unclear, and since documentation tends to be so fragmented and scattered, it's not even necessarily a good bet that any given documentation actually applies to anything anymore.
Though I am supposed to be working on some of this design documentation, I have also found myself very confused at times myself trying to work with it, often to the point of not even wanting to touch it because I'm not sure why most of the content is even there, or why such emphasis is placed on certain things that appear tangential at best, or why it starts with nomenclature when surely the problem it's trying to address would be more important. Big words, apparently redundant sections, and a lack of clarity as to how it's supposed to work on the back end don't generally help matters either.
Because I don't understand it, I don't know how it could be improved. I don't know what could be done about it, or what could make it more accessible or faster to scan and more able to reassure the users that yes, this thing here, it's perfectly sensible and you can see it too, nothing to worry about.
Instead it's like Foundation is working on this thing, it's supposed to do stuff and now you have a funny icon in your personal toolbar. Who knows why. Got lost trying to read the documentation after the fourth section of goals.
Now that may be an exaggeration, but I have gotten similarly lost trying to follow Flow's documentation even after almost three months working with it. Eventually found it easier to not even try to use it - just started my own, got thoughts down, started making mockups. While with any luck these should be largely applicable to Flow itself, I can't help but wonder if this isn't a somewhat normal occurrence - where someone doesn't follow something, forks or writes their own documentation, and then... who knows. Would explain some of the stranger things.
