Reference

From PRPL
Revision as of 15:04, 11 September 2014 by Eschultz (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

References are the lowest level of a project's documentation. The purpose of references is to provide high quality explanations of APIs, functions and data structures.

Projects often make a few mistakes with references that are important to avoid. References should NOT be the only documentation on a project. Often times projects create autogenerated documentation, post it online and think they're done. This is not remotely sufficient for documentation and doesn't provide users with enough high-level information to understand the project.

Additionally, references should consist of more than autogenerated documentation. Autogenerated documentation is, at best, a starting point for creating references. References need to include more detail than a list of the functions and data structures, they should have enough information for users to understand what the functions and data structures do and how they fit together. Simple examples, with clear explanations of how to use the functionality.

TODO