The famous “chicken or egg” dilemma is similar to a common problem faced by tech writers — what goes first? Everything can’t be first, and all new concepts can’t be explained simultaneously. So we make choices and organize content in a manner that we hope will work effectively for each reader.
Sometimes we don’t get it right. Here’s one way we can miss: we introduce Concept A. As part of A’s description, we use Term 1. We decide that now isn’t the time to tangent into a discussion on Term 1, so we provide just enough information so Term 1 makes sense in the context of Concept A, and we go more into depth on Term 1 later.
This approach can miss when our reader doesn’t realize that there is more to be learned about Term 1 elsewhere, and so he acts on his understanding of Term 1 from Concept A but gets it wrong.
An actual example involves the DPM storage pool. We refer to the storage pool disk(s) in the system requirements, but the specific disk types that can be used are listed later in the storage pool section of the documentation. So a customer looking only at the system requirements wouldn’t realize that DPM does not support using USB or IEEE 1394 disks in the storage pool.
There are several ways we could have fixed it. The supported disk types could have been repeated in the system requirements. Or, the storage pool reference in system requirements could have been linked to the storage pool section. Until our next opportunity to publish, though, we’ll just use avenues like the newsgroups and this blog to remind everyone that DPM does not support USB/1394 disks in the storage pool.