I've written a couple of
technical nodes recently, the first nodes I've written in quite some time. For both these nodes, I got a few comments along the lines of "This is too technical, there is not enough explanation, no layman could understand this." In retrospect, the former (
lock convoying) had absolutely no introduction in its first incarnation, and really was very
layman-unfriendly. The second (
non-blocking synchronization), however, started out with the intro it has now, and overall, I thought it made a decent effort at providing the layman with a general idea of the issue at hand, while giving the clergy (so to speak; the clergy of the Church of
Computer Science, anyway) a good definition and explanation of the term, and providing both with points of departure for further reading in related topics by way of hardlinks.
When I write on a very specific technical term, like NBS or lock convoying, I feel like my first and foremost duty is to the technical person who needs a clear, conscise, and easy-to-find definition of the term. After all, the writeup is only in "New Writeups" for a few hours, and after that the odds are that anyone who finds it is either looking specifically for it, or has stumbled onto it by way of some related node; in either case it is highly unlikely that such a person is a layperson with no knowledge of the subject. On the other hand, I do recognize that I do also have a duty to the odd layperson who finds my writeup, and that his reaction to the entire thing must, ideally, consist of quite a bit more than a "wtf?". So my general goal for the layman when writing these kinds of nodes is for him to take hom a general feel for what the term means, the issues at hand, and some links to further information if he's interested. To some extent, also, I am expecting him to read some of the hardlinks I have provided, particularly when he does not understand a hardlinked term. However, I specifically do not expect him to understand the entire content of the node.
A different approach would be to explain everything. For example, in the NBS node, I could have engaged in short explanations of each of the four problems I mentioned with regards to lock-based synchronization; I could have explained what mutexes are; atomicity; compare-and-swap; etc. What I have thus far preferred to do, is to write my writeup without these explanations of tangential terms, and provide hardlinks to the relevant nodes (and, where these links do not lead to a relevant writeup, create such a writeup in said node). In any case, my point in writing all this is to ask, is my way the correct way for E2, or should I start writing technical term writeups with a lot more tangential substance, that are perhaps somewhat less useful to the technical reader who is looking for very specific information, but more useful to the layperson?