bytesize

I've been thinking a lot about the assumptions we make about domain knowledge when writing guides and documentation. Far too often, I've found myself needing to look up a host of terms and acronyms just to translate this jargon into plain English. Now, I've spent a lot of time doing this and gotten reasonably good at parsing text like this (often in the form of technical documentation). But, consider a developer with less experience and/or domain knowledge. They would be left not even knowing where to begin. All because the text preferred jargon over simple explanations.

I've found, where possible, complex terms should be accompanied by a simple explanation (or a link to one). That is, of course, if these complex terms are really necessary. It's not uncommon for them to be replaced with simpler, more intuitive ones. In fact, writing simpler documentation can benefit more than just novice developers. Simpler documentation can mean a faster turnaround time for newcomers to the project regardless of experience. It can also make referencing these documents easier, limiting time spent switching contexts to look up definitions/meanings. When you fail to describe things in simple, concrete terms, that burden falls upon the reader. This up-front cost to understanding your documentation should be as minimal as possible. If you force people to pay entrance fees, they'll start looking elsewhere for free admission.