Skip to content

Latest commit

 

History

History
209 lines (192 loc) · 16 KB

roadmap.md

File metadata and controls

209 lines (192 loc) · 16 KB
Raw

JSON Schema

A roadmap represents a high-level plan for your project or team.

Properties

  • title (string): A brief title which describes this roadmap.
  • description (string): A markdown formatted description of what this roadmap represents and any additional context which may be useful to a reader.
  • logo (object): A path to your project logo. This might be a good brand for your roadmap.Best fit would be some small-icon.
    • filename (string, required): Your logo MUST placed where your roadmap.yml lives.
    • copyright_notice (string): If there is any copyright-notice, this would be rendered as alt-text.
  • visionstatement (string): A markdown formatted project pr product visionstatement. A product vision describes the ideal product from the customer's perspective. The leitmotif of a product vision is therefore the question of how the product can optimally address and solve the customer's problem or needs.
  • authors (array): A list of authors who were/are involved in the creation of the roadmap.
  • releases (array): A list of releases which provide enhancements in the form of deliverables to the stakeholders.
  • timeline (array): The list of important dates which relate to this roadmap.
  • objectives (array): The list of objectives which the team is working towards over the course of this roadmap.
  • milestones (array): The list of milestones which act as indicators of progress for this roadmap.

Definitions

  • Author (object): The details of an author responsible for this roadmap, in case a reader has questions.

    • name (string, required): The full name of the author.
    • contact (string, required): The contact address for the author - usually their email, but may also be an IM handle or otherwise.

    Examples:

    contact: [email protected]
name: John Doe

  • TimelineMarker (object): An important date which relates to this roadmap.

    • date (string, format: date, required): The date that this timeline marker is associated with.
    • title (string, required): A brief name associated with this timeline marker to describe it.
    • description (string): A markdown formatted description of what this timeline marker represents, or additional context associated with it.

    Examples:

    date: '2023-01-15'
description: Something really important happens on this date and we will all become
    lucky people
title: Something really important happens

  • Objective (object): An objective describes a high level goal for the team. It is usually something that will be worked towards over several milestones and might not have a clear definition of done.

    • title (string, required): A brief name associated with this objective which describes the intended outcome.
    • description (string): A markdown formatted description of what this objective represents and how it influences the direction that the team is moving in.
    • date (string, format: date): The date that this objective should or is reached.
    • state: Refer to #/definitions/ObjectiveState.
    • reference: Refer to #/definitions/Reference.
    • milestones (array): The list of milestones which act as indicators of progress for this objective.
    • keyresults (array): The list of key-results which make up this Objective. Key-Results usually map to specific pieces of work which may be delegated to a member of your team.
    • todos (array): A List of Todos, which are necessary to clarify the objective, e.g. a open point. The intend of the todos is something around the roadmap creation, not to do something to achieve an roadmap objective.

    Examples:

    description: Great documentation is critical to the adoption of our project and is
    an integral part of everything we introduce.
reference:
    link: https://example.com
    name: example.com
state: IDEA
title: Our users love the documentation we provide
    description: "The goal of this project is, primarily, to provide a single schema that\
    \ can be used by different teams to describe the work they are doing and their\
    \ future intentions. \n      The usefulness and applicability of this schema to\
    \ real-world problem domains will determine whether anything else we do here is\
    \ of value."
keyresults:
-   description: Develop a schema that fulfills the main requirements of the objective
    reference:
        link: https://example.com
        name: example.com
    requirement: MUST
    state: DONE
    title: Provide a schema defintion
reference:
    link: https://example.com
    name: example.com
state: IDEA
title: We provide a single, universal, schema for high-level planning

  • Milestone (object): An indicator of progress for this roadmap. Usually milestones are collections of deliverables which, when considered together, represent a shift in the value delivered by a team or project.

    • id (string): A human-readable unique identifier for this milestone.
    • _id (string): unique identifier for this milestone, derived from milestone.id - if unset calculated based on milestone order.
    • title (string, required): A brief name associated with this milestone to describe the value shift.
    • description (string): A markdown formatted description of what this milestone represents and, if appropriate, the justification for its presence and prioritization.
    • date (string, format: date): The date that this milestone should or is reached.
    • state: Refer to #/definitions/MilestoneState.
    • reference: Refer to #/definitions/Reference.
    • deliverables (array): The list of deliverables which make up this milestone. Deliverables usually map to specific pieces of work which may be delegated to a member of your team.
    • todos (array): A List of Todos, which are necessary to clarify the milestone, e.g. a open point. The intend of the todos is something around the roadmap creation, not to do something to achieve an roadmap objective.

    Examples:

    deliverables:
-   description: Create a documentation repository and configure the build tooling
        to generate and publish a website.
    requirement: MUST
    state: DOING
    title: Setup Docs Repo
-   description: Put together a getting started guide for new customers.
    requirement: SHOULD
    state: TODO
    title: Getting Started Guide
description: Publish a documentation website for the project, with information that
    customers can use to understand how to use it.
title: Documentation Website

  • Deliverable (object): A specific piece of work which may be delegated to a member of the team.

    • title (string, required): A brief name describing this deliverable.
    • description (string): A markdown formatted description of what this deliverable entails and why it is necessary for this milestone.
    • date (string): the date (quarter, month, day,...) where the keyresult should be achieved.
    • reference: Refer to #/definitions/Reference.
    • state: Refer to #/definitions/DeliverableState.
    • requirement: Refer to #/definitions/Requirement.
    • todos (array): A List of Todos, which are necessary to clarify the deliverable, e.g. a open point. The intend of the todos is something around the roadmap creation, not to do something to achieve an roadmap objective.
    • quantifiers: Refer to #/definitions/Quantifiers.

  • Keyresult (object): A specific piece of work which may be delegated to a member of the team.

    • title (string, required): A brief name describing this result.
    • description (string): A markdown formatted description of what this result entails and why it is necessary for this objective.
    • date (string): the date (quarter, month, day,...) where the keyresult should be achieved.
    • reference: Refer to #/definitions/Reference.
    • state: Refer to #/definitions/DeliverableState.
    • requirement: Refer to #/definitions/Requirement.
    • todos (array): A List of Todos, which are necessary to clarify the keyresult, e.g. a open point. The intend of the todos is something around the roadmap creation, not to do something to achieve an roadmap objective.
    • quantifiers: Refer to #/definitions/Quantifiers.

  • Todo (object): A Todo which is necessary to clarify a roadmap item, e.g. a open point to clarify a milestone. The intend of the todo is something around the roadmap creation, not to do something to achieve an roadmap item.

    • title (string, required): A brief title describing the todo.
    • description (string): A markdown formatted description of what this todo entails and what to do.
    • state: Refer to #/definitions/TodoState.

  • Quantifiers (object): Quantifiers attempt to convert or describe particular properties and aspects of certain roadmap elements into mathematically measurable values. This involves reformulating properties and assumptions of key results or deliverables into numerical values. Not all aspects of roadmap are currently supported.

    • weighted_shortest_job_first (['number', 'null']): A value between 0 (lowest) and 30 (highest), describing, the weighet shortest job first size (according to docs/wsjf.md). If weighted_shortest_job_first is NULL weighted_shortest_job_first is calculated during processing, if all criteria of calculation are meet. WSJF is a prioritization method that helps to identify the greatest possible value of a planned result in relation to its effort. All Dimension are normally given independently WSJF = CoD(Cost of Delay) / Job Size CoD is: (user_business_value + time_criticality + opportunity_or_risk) In Order to calculate, we need all of them. Minimum: 0.0. Maximum: 30.0. Default: null.
    • cost_of_delay (['integer', 'null']): A value between 0 (lowest) and 30 (highest), describing a measurement of the economic value of a job over time. According to docs/wsjf.md CoD is calculated using user_business_value + time_criticality + opportunity_enablement_or_risk_reduction If cost_of_delay is NULL cost_of_delay is calculated during processing, if all criteria are given and have values >= 0. Minimum: 0. Maximum: 30. Default: null.
    • user_business_value (['integer', 'null']): A value between 0 (lowest) and 10 (highest), describing, how much the customer (user value) or the company (business value) benefits from the result. Minimum: 0. Maximum: 10. Default: null.
    • time_criticality (['integer', 'null']): A value between 0 (lowest) and 10 (highest), describing, how time critical the item ist. E.g. are there fixed deadlines for certain results, e.g. because there are assurances to partners or customers, contractual agreements or legal deadlines? Is there a risk that the value can no longer be achieved if the deadline is not met? Will a possible completion in a few months still have the same value as today? Minimum: 0. Maximum: 10. Default: null.
    • opportunity_enablement_or_risk_reduction (['integer', 'null']): A value between 0 (lowest) and 10 (highest), describing if there is any opportunity enablement or risk reduction by achiving this item. E.g. By achieving the result, are we building up certain technical or specialist skills from which we will benefit later in the implementation or which will allow us to achieve certain later results more easily or at all? Are there risks that are minimized by achieving a certain result? Minimum: 0. Maximum: 10. Default: null.
    • jobsize (['integer', 'null']): A value between 1 (shortest) and 10 (longest), describing, the approximation of the expected effort or statement about how long it takes to deliver the value for a delivery or result. If you really need a Jobsize of 0, something went wrong.. Minimum: 1. Default: null.

    Examples:

    $comment: 'Item with a wsjf of 3: ((1 + 1+ 1) / 1) - mid ranked'
cost_of_delay: 3
jobsize: 1
opportunity_enablement_or_risk_reduction: 1
time_criticality: 1
user_business_value: 1
weighted_shortest_job_first: 3.0
    $comment: 'Item with a wsjf of 12: ((10 + 1+ 1) / 1) - ranked high'
cost_of_delay: 12
jobsize: 1
opportunity_enablement_or_risk_reduction: 1
time_criticality: 1
user_business_value: 10
weighted_shortest_job_first: 12
    $comment: 'Item with a wsjf of 1.2: ((10 + 1+ 1) / 10) -> ranked low'
cost_of_delay: 12
jobsize: 10
opportunity_enablement_or_risk_reduction: 1
time_criticality: 1
user_business_value: 10
weighted_shortest_job_first: 1.2

  • Reference (object): A reference to a file or url with additional context which may be useful to a reader.

    • name (string): a short-name for the uri.
    • description (string): a describtion in natural words, what someone could expect by using the link of this reference.
    • link (string, format: uri, required): A URI at which additional information about this deliverable may be found (whether that be documentation or a tracking ticket).

  • Release (object): releases which provide enhancements in the form of deliverables to the stakeholders.

    • tag (string, required): a short-name for the release.
    • description (string): a describtion in natural words,what should or must be part of this release.
    • reference: Refer to #/definitions/Reference.

  • DeliverableState (string): The state of an item on the roadmap. Must be one of: ["TODO", "DOING", "DONE", "SKIP"]. Default: "TODO".

  • ObjectiveState (string): The state of an objective-item. Must be one of: ["IDEA", "PLANNED", "COMMITED", "ACHIEVED", "SKIP"]. Default: "IDEA".

  • MilestoneState (string): The state of an milestone-item. Must be one of: ["IDEA", "PLANNED", "COMMITED", "REACHED", "SKIP"]. Default: "IDEA".

  • Requirement (string): An RFC2119 verb which describes how a specific requirement should be treated. Must be one of: ["MUST", "SHOULD", "MAY"]. Default: "SHOULD".

  • TodoState (string): The state of an item on a todo-list. Must be one of: ["OPEN", "DOING", "CLOSED"]. Default: "OPEN".