Project Documentation ===================== Project documentation should include the following types of information; Introduction The name and purpose of the project. Contents A general explanation of the project contents and structure. Terms and Conditions A statement of the usage and copying terms and conditions. Install Instructions Installation information and instructions. Usage Instructions Usage information and instructions. Support Instructions Support information and instructions. Should include contacts, tools, procedures, and conventions for user-level assistance. Development Instructions Development information and instructions. Should include contacts, tools, procedures, and conventions for developer-level contributions. Design Details Design overview and explanations. Should include details of research done, similar or related projects, origins and influences, general design philosophy, design decisions taken or rejected, and a design description. Future Plans An indication of future directions and plans. Past History A record of past development and events. Credits A record of contributors and their contributions. References References to any required and related projects. Definitions Definitions of terminology and acronyms used by the project. GNU Documents ------------- The following documents are typically generated and required by GNU autotools. They are mostly described by the GNU documentation standards. They can be combined and/or omitted, but GNU autotools require explicit "--foreign" flags to stop them complaining. README Introduction document which gives the name of the package, a general description of its purpose, and an overview of the distribution's contents. It should include or refer to install, usage, and support instructions. It may include or refer to development instructions. INSTALL Installation instructions for installing distribution tarball. May be omitted and incorporated into README. COPYING Licence information. Typically a copy of the GPL. AUTHORS Lists the original authors and significant contributors to the project. THANKS Lists all contributors, preferably with a brief description of their contributions with references to patch and bug numbers. NEWS User visible change history for each release in order of most recent first. Should refer to bug and patch numbers where possible. Should also include completed items removed from TODO. TODO A list of outstanding tasks in order of highest priority first. Should only include outstanding items. Items should be removed from TODO and put into NEWS as they are completed. ChangeLog CVS/SVN level changelog, preferably auto-generated using something like cvs2cl in the Makefile and not included in the CVS/SVN archive. Extra User Documents -------------------- These documents are usually incorporated into the README, but if they are large they can be split out into these sub-documents or put on the project's wiki. USAGE Describes how to use the project item after installation. Simple usage instructions are usually incorporated into README, but often more extensive instructions are in man pages in the doc/ directory. SUPPORT Describes contacts, tools, procedures, and conventions used by the project for user-level support and contributions. This includes things like bug reports and mailing lists. This information is normally included in README, but if it is large it can be split out into this document. Extra Developer Documents ------------------------- These documents are targeted at developers, not users. They contain information for developers that users will usually not want to know. For new projects without many releases they may be initially incorporated into the main README, but once a project is large enough to have distinct groups of users and developers they should be split out into these sub-documents or put on the project's wiki. DEVELOPMENT Describes contacts, tools, procedures, and conventions used by the project for developer-level support and contributions. It should have a general discription of the repository, and an overview of contents that are excluded or generated for the distribution tarball. It should include suggestions and procedures for doing development, testing, debugging, patches, commits, and releases. DESIGN Describes and justifies the design of the project. This includes things like details of research done, similar or related projects highlighting similarities and differences, origins and influences on the project, the general design philosophy used, design decisions taken or rejected with explanations why, and a description of the overall design. This is usually omitted from distribution release tarballs, and is best put on the project's wiki. Other Documents --------------- These are other documents commonly seen that usually replicate parts of the documents described above. They should probably not be used for new projects. README.CVS/SVN This is an older version of DEVELOPMENT. Extends on README to include additional information relevant to the CVS/SVN archive. Includes a general discription of the CVS/SVN archive, and an overview of contents in CVS that are excluded or generated for the distribution tarball. It should include development information including contacts, tools, procedures, and conventions for developer-level contributions. May also incorporate and replace INSTALL.CVS/SVN. INSTALL.CVS/SVN This is an older version of parts of DEVELOPMENT. Describes the installation process from CVS/SVN. May be incorporated into README.CVS/SVN. CONTRIBUTING An alternative name for DEVELOPMENT suggested by the `flint http://github.com/pengwynn/flint`_ project. Development Tracking -------------------- The following are entirely optional. Their main purpose is to provide a more detailed audit trail of development. This is typically for time/cost/blame tracking of commercial projects. They may be replaced by other more advanced development tracking tools, and will never be included in distribution tarballs. They may also be in a special "swf" (Software Working File) or "doc" directory. DIARY A development journal, recording times, durations, and descriptions of work done by developers. Useful for both documenting development history, and for tracking developer hours. Not required for projects using better development tracking tools. MAIL An mbox format mail archive of project related emails. For projects with proper mailing list archives this is not required. Document Tree ------------- The document heirachy of references or mergable components can be shown as follows:: README |______________________ | \ \ \ INSTALL USAGE SUPPORT DEVELOPMENT | DESIGN Any of these documents can be incorporated into the document above. ---- $Id: ProjectDocs.txt,v 69a01169087f 2014/11/27 00:12:55 abo $