Even though I typically enjoy structured documents, I have to say that my first impression of
PatternForms (such as the
CanonicalForm and
GoFform) was that:
- They placed an unnatural order on documents.
- They relied on previous understanding of the form. ("'Forces'? Forces on what?", I asked.)
Over time, I've learned to understand
PatternForm, and now feel that in many cases using it is a great way to document an idea (for example, "
LetsPlayTeam").
My point is this: There is a certain amount of overhead that each person will have to go through before
PatternForm becomes a natural way to read. Until the reader has gone through this, they could be distracted by it, defeating the point.
Solutions:
- If a document resists being put into the form, consider it a TextSmell to be heeded.
- Put a link to the PatternForm you used. This will be redundant to those who already get it, but for those who don't, it could help a lot.
Forces are easier to understand if you understand
EasternPhilosophy. Other lessons from the East that are important include simplicity, especially in names and explanations.
The point is that the PatternForms rest on previously known information, which this statement supports.