RKT principles for software reuse
One of the most significant obstacles to software reuse from external libraries is the effort to become familiar with what exists. Hypertext documentation using the RKT design principles greatly simplify this task, leading to "Rapid Knowledge Transfer."
The 5 RKT design principles enable ultra-efficient access to documentation.
The 5 principles and their application in general are described in more detail at http://www.mibsoftware.com/rktprin/
- One Topic per Page
- Unique, Descriptive Titles
- On Site Search
- Topic Clusters
- Dense Hyperlinks
The "man page" style of documentation, with synopsis, error handling, descriptions, is a "must-have". But applying the RKT design principles to software library documentation means the following "extras"
- Example code which can be "cut and pasted." Most functions are
used in a common paradigm of loops, error handling, etc.
Sometimes it is easier to learn by example than description.
- Links directly to the header files and source code
If the docs don't explain something completely, view the implementation
- Portability notes
Write O/S independent code, or be aware of what is different between systems.
- Issues list. Known defects, missing features, discussion, etc.
RKT design principles As originally developed for the Usenet RKT, a 650+ page resource with more than 9000 hyperlinks.
Up To: The LibMib Software Component Library
Up To: Mib Software home page
This Libmib documentation may not be distributed.
Copyright 1998-1999, Forrest J. Cavalier III
High Reuse Software Development