Still about improving the official documentation.
|modified content, my style – snapshot for jQuery $( String, Object )
|official content, my style – snapshot for jQuery $( String, Object )
|official content & style – snapshot for jQuery $( String, Object )
Examples on a common ground
The use cases in a software documentation are very important. And as a general principle, the more they are standardized around some basic concepts, the more useful they are, because the reader can easily tell the differences and concentrate on them. As much as possible the differences should be limited to what is special about the functionality being described.
- An examples element in the documentation XML has 5 (sub)elements: desc, code, comment, before, after. The answer to why I added the comment element is given below.
- The labels for an example subelements (as they now appear in my working sample) are: Example, Solution, Comment, Before, and After (respectively)
- Example must be a description of a problem to solve, and I chose to begin it with a “To” + infinitive form, because this is the standard for problems at school; it’s not required that the functionality be central to it. A real and bigger example is preferable to a shorter but artificial one. The same example used over and over, either for showing different solutions or different functionalities should be good, because of the standard effect. Different solutions should be referenced one from the others.
- Solution must be limited to the jQuery code excerpt that solves the problem; and it should be complete, so that it could be introduced in the usual framework as is, and produce the After when applied to the Before
- Comment can be anything worth to note about the Solution, and the other elements. Less noise, the better. However this is the preferred space for all that is not strictly a problem or solution description. Really the Comment exists for segregating the talk from the data.
- Before must be the test context to which the solution is applied, better if represented by a meaningful HTML excerpt.
- After must be the Before context as changed by the application of the solution, better if represented by a meaningful HTML excerpt.
- Before and After should work together, and the result of their comparison should look like a diff result.
- Before and After should also provide context for themselves. That is, <div></div> seems a good choice for a Before but it’s not, beacuse it has no clear context. In fact <body><div></div></body> is much better, because the reader now knows the DOM completely and can make safe assumptions
- In general, each functionality should have at least one example, and more often than not, just one example should be fine.
- The challenge is to provide a good example where
- the issue is taken from the real world and is something at which jQuery excels
- the problem can be cleanly stated and easily understood
- the solution is short and elegant
- the comment is short and remarks subtleties to watch out
- the Before and After are short, clean, and they work side by side in a diff fashion
Highlighting
The Solution, Before and After sections have to show context, but they exist mainly to show how to use the functionality. So I’ve introduced a means for drawing the reader’s attention to what is really important. All the text which in the documentation XML is wrapped by a grave accent (`) is highlighted using a css style.