Feature Documentation - juju/juju GitHub Wiki

FEATURE DOCUMENTATION

    +-----------+       
    | Roadmap   |
    +-----------+       
          |   
          |     
          |                    
          V                    
    +-----------+       
    |   Brief   |
    +-----------+       
          |   
          |     
          |                    
          V                    
    +-----------+       
    |  One Page |
    +-----------+       
          |   
          |     
          |                    
          V                    
    +-----------+        +------------+
    |   User    |------->| Acceptance |
    | Stories   |-+      |  Criteria  |-+
    +-----------+ |-+    +------------+ |-+
       +----------+ |        +----------+ |
         +----------+          +----------+

Each element of the feature documentation is developed sequentially as we get or discover new information. We should build these elements up as we dive in and iterate on individual components where needed.

Roadmap, Brief and One Page would be produced as part of Leads Sprint in close collaboration with Product Owner and Product Manager.

User Stories and Acceptance Criteria are more closely aligned to individual tasks that go on our squad boards. However, these cards should also be assembled in a document for easy grouping and access.

ROADMAP

Audience

  • Product Manager
  • Leads

BRIEF

Purpose

  • Define a problem that feature will resolve
  • Define solution that will solve the problem
  • Identify Feature buddies

Audience

  • Product Manager
  • Leads

ONE PAGE

The usefulness and the usability of a feature is especially explicit when considering its user-facing components.

For Juju core, user-facing components are either CLI or API calls. These calls need to be documented first and approved by Product Manager.

When defining these interface calls, use the most common use case as a base and add more complex use cases iteratively. This will enable us to present the simple scenario and as well as cover all flags and options to cater for all known scenarios under consideration.

Purpose

  • Establish user-facing interface - CLI, API
  • Get Product Manager approval
  • Identify related Features

Audience

  • Product Manager
  • Leads
  • Core
  • QA
  • Technical Writers
  • Feature buddies

USER STORIES

A collection of User Stories that contribute to the Feature.

Individual User Story describes component or a task, usually focusing on a task that user needs to perform intentionally. Task-centric User Stories ensure that implementation and design can be done completely separately, not dictated. Example below demonstrates difference.

It is important for a User Story to highlight the business value that it brings. This is where we justify why this work is useful.

A User Story is a releasable planning item and is a token for conversation with feature buddies, core developers, charmers and other interested parties.

A User Story has a title and a content. Its title is usually a verb-noun combination whereas its content has information about WHO will get WHAT BENEFIT by HAVING or DOING WHAT.

To remove ambiguity and minimise interpretation, stories should be laconic. Avoid prose as much as you can!

Suggested Format

    As a <type of user, role>
    I want to <perform a task>
    So that I can <reach some goal, business value to be delivered>

Task-centric example (recommended):

    As a gardener
    I want to dig a hole
    so that I can plant a tree

Tool- or feature-centric example (please avoid):

    As a gardener
    I want a shovel
    so that I can [dig a hole to] plant a tree

Purpose

  • Define user benefits
  • Separate needs (requirements) from how-to (implementation)

Audience

  • Product Manager
  • Core
  • QA
  • Technical Writers
  • Feature buddies

ACCEPTANCE CRITERIA

A collection of acceptance criteria grouped by User Stories. Each criterion describes a condition that completed User Story must satisfy. They are written in terms of usage and easily translate to functional tests, release notes details and user facing documentation. Acceptance Criteria must cover both failure and success paths. Consequently, there would be at least 2 criteria per each User Story. Acceptance criteria should also cover all aspects of quality where:

Objective quality is visible, measurable and easily validated characteristics. Does Juju perform as specified and is bug-free. Subjective quality is user perception of Juju. Is it simple, efficient to use?

Each Criterion should resonate with at least one of the four heuristics:

1. Bare Necessity: What is the essential functionality necessary to demonstrate the simplest use of the task User Story describes?

2. Capability & Flexibility: What would make this Story useful in more situations? What would allow the Story to be used in alternative ways? What elements of the Story are optional?

3. Safety & Security: What would make this Story safer to use? What would make this Story more secure? These are characteristics that help prevent errors or validate data to prevent bad information from entering our system.

4. Usability, Performance, Appeal: What would make this Story more desirable and easy to use? This includes adjustments to improve usability, aesthetic appeal, performance. For example, short cuts or speed keys.

Each criterion must talk about its prerequisites CONTEXT, stimuli INPUT and an expected result OUTPUT.

Suggested Format

    Given <preconditions>
    When <an action or an even takes place>
    Then <results achieved>

Purpose

  • Define usage expectations
  • Define usage tests
  • Define manual/documentation details
  • Define feature boundaries
  • Quantify development progress

Audience

  • Product User
  • Core
  • QA
  • Technical Writers
  • Feature buddies