Documenting the Performance Platform

Documentation strategy

Documentation is something that is never "done", because there is always room to improve existing content and write more. In order to document the Performance Platform, we should write quick documentation as new software and features are developed, but not aim for comprehensive content up front. Rather, as questions are asked, we should respond by updating the documentation to explain and clarify, then share the new URL (respond to actual user needs, not perceived needs).

Different audiences of documentation

• documentation for the PP team should live in this wiki
• documentation for the people writing the software should live with the software (repo README, repo wiki)
• documentation for people using the software should live either with the software (repo README, repo wiki) or in a man page or other suitable medium that is appropriate for the software at hand
• documentation for people wanting to use the Performance Platform as a whole lives in libretto, which will overlap with the content described above, and it should duplicate a minimum of it, ideally linking instead

Different types of documentation

There are three broad types of documentation. All are required.

1. New user documentation — high level introductions, beginner's guides, etc
2. Usage documentation – how to use tools, APIs, modify code, maintain sites, etc
3. Reference documentation — every bit of every thing explained in detail