A reformatted and augmented TiddlyWiki/Dev documentation file (The following is also found in the tiddler ___nspies Notes on this TW
Although I have combed through the tiddlers in this stack, in some cases 3 times, the overall style is a bit uneven and is left that way to leave a comparison between different levels of "outline fragmentation" that are decided to be better or worse.
There is a lot of redundant explanation in this TW, which needs, IMO, to be wrung out, to reduce it to a terse statement about how things work. This would make it easier to read and easier to tell when one topic is covered in a difinitive manner.
An example of this is the statement that 'everything is a tiddler except the microkernal' seems to drop in in different contexts.
I made the argument that, for learning, such a flexible medium as TW must be subdued somewhat, as I believe that, while free branching is invaluable for many purposes, it also obscures the "optimal path" (or "best curriculum") through all the material to be mastered. This is easy enough to achieve in a book or video, but tricky in branching multimedia, as it is easy to lose sight of the forest for the trees, particularly if there are not clearly-defined paths or only one path through the material presented.
This is probably more difficult for someone steeped in TW to fully realize that someone who really knows next to nothing at the outset, making it difficult to write the documentation.
Perhaps user documentation should be tied in with developer documentation, as they are hardly mutually exclusive, and it would provide many more paths from which to choose "optimal paths" for different users at different levels of competence.
There should be an entirely different infrastructure built in to test to the learner's mastery. This could be easily be tucked out of the way if the documentation is simply used as a reference (which brings up the need for a glossary of terms, indices, lists of figures, and whatever other paraphenalia that has developed for books over the centuries to make it more effective as a reference, both for learners and power users).
This is a daunting task, but without it, TW will only make real sense to those who have spent lots of time hacking with it, whereas the point of documentation is to make it possible for any reasonably intelligent user to be a competent author of macros, modules and the like, so it is vitally important to do it right.
The unique opportunity afforded by TW is that it has many avenues built-in to make documentation of itself function well for many different levels of users, and at the same time be almost transparently clear to read, because of ease with which it may be formatted (and "pre-parsed"). Just this last point alone would make it unlike most computer program documentation, which tends to read like legal documents, which are in many ways obfuscating, even while intending not to be.