GSoD: User story based documentation

For the GSoD 2019 project (1) User story based documentation we will work with technical writers to develop their proposal. We will help with user stories, an agile programming technique to informally define requirements.

Objective

Create documentation (starting from existing MDAnalysis docs) addressing common well-known use cases of the library. The structure should be at a higher level than the existing module-level default documentation and similar to the structure used for libraries such as scikit-learn and pytorch.

Background

• existing MDAnalysis docs
• notes on restructuring docs
• notes on expanding tutorials because some of the topics should also be addressed at the broader, more inclusive level of the main user docs

User stories

User stories, an agile programming technique to informally define requirements. We will use a common template to develop key requirements that the docs should cover. Typically, these user stories will be written from the perspective of the user, i.e., with the role "user".

Each user story gets a title (and its own subsection under User stories for the documentation and the has two short sections: The description contains the place holders that are replaced with content defining role, action, and optionally the benefit. The acceptance criteria briefly described what constitutes an acceptable solution.

Example

1. Title: Selecting atoms by residue
2. Description: As a user I need to be able to select atoms depending on the residue that they belong to.
3. Acceptance criteria: I can understand which method to use, given that I have a universe, and I understand what parameters I have to supply to make my selection.

Template

1. Title:
2. Description: "As a , I need to be able to [because ].”
3. Acceptance criteria:

User stories for the documentation

User stories should define what is required for the docs. Each story gets its own section and header and uses the template above.

TODO