Document

In order for your software package to be useful, documentation is required that describes how your software can be installed, operated, used and improved:

• Those who want to use your package need information,

  • what problems your software solves and what the main features and limitations of the software are (→ README)

  • how the software can be used as an example

  • what changes have come in more recent software versions (→ CHANGELOG)

• Those who want to run the software need an installation guide for your software and the required dependencies.

• Those who want to improve the software need information about

  • how to help improve the product with bug fixes (→ CONTRIBUTING)

  • how to report security vulnerabilities (→ SECURITY)

  • how to communicate with others (→ CODE_OF_CONDUCT)

All together need information on how the product is licensed (LICENSE file or LICENSES folder, → LICENSE) and how to get help if needed.

Tip

cusy seminars:

• Software documentation with Sphinx

• Technical writing

See also

• Eric Holscher: Why You Shouldn’t Use “Markdown” for Documentation

• Tom Johnson: 10 reasons for moving away from DITA

• Tom Johnson: Jekyll versus DITA

• Google developer documentation style guide

• Google Technical Writing Courses for Engineers