roadmap

README

Road map

Generate your team's road-maps from structured data

This project is designed to make visualizing and tweaking your road maps as easy and straightforward as possible. There are a number of good options out there, including PowerPoint, Visio, LucidChart, Draw.io, GraphViz and just plain old lists - however none of them have made me particularly excited about drawing up our team's road maps and many of them make future edits difficult.

The goal here is to change that, by defining your road map in everyone's least loved markup language: YAML. An example road map might look something like the following.

Usage

GraphViz

The easiest way to get started viewing your road map is to output a GraphViz DOT file which can be rendered using any GraphViz renderer, like GraphViz Online. To do so, you'll need Go installed on your machine and then you can simply run:

# Install the tool
go install github.com/SierraSoftworks/roadmap/tools/roadmap-graphviz@latest

# Run the tool
roadmap-graphviz --in my-roadmap.yml -out my-roadmap.dot

Drop the DOT file into your GraphViz renderer of choice and you're good to go!

Example

title: Example Road Map
description: |
    This is an example of what a road map might look like.

authors:
  - name: Benjamin Pannell
    email: contact@sierrasoftworks.com

timeline:
  - date: 2021-04-21
    title: Project Start
    description: This is when we will start working on the project, get the team ready!

objectives:
  - title: Market Dominance
    description: |
      Provide actionable analytics drawn from big data to improve our brand identity in
      the advertainment sector, maximizing clickbait and establishing ourselves as a disruptor
      in this industry.

milestones:
  - id: team
    title: Build the Team
    description: We don't yet have anyone, that's not gonna work...
    deliverables:
      - title: Team Lead
        state: TODO
        requirement: MUST
        description: This person needs to know enough about this domain to be able to run with the project.

      - title: Senior Engineer 1
      - title: Intern 1..50
        description: This should be cheaper than hiring a proper team (right?).

  - id: done
    title: Finish the Project
    description: We don't need other milestones, do we?
    dependencies:
      - team
    deliverables:
      - title: MVP
        description: Who needs a polished product? Let's just ship the MVP and call it done.
      - title: Marketing
      - title: VC Funding
      - title: Yacht
        reference: https://lmgtfy.app/?q=yacht&t=i

Documentation

Index

• func Schema() string
• type Author
  • func (a *Author) ID() string
• type Deliverable
  • func (d *Deliverable) ID() string
• type Milestone
  • func (m *Milestone) ID() string
• type Objective
  • func (o *Objective) ID() string
• type Roadmap
  • func Parse(in []byte) (*Roadmap, error)
  • func (r *Roadmap) Validate() error
• type TimelineEntry
  • func (t *TimelineEntry) ID() string

Functions

func Schema

func Schema() string

Schema will return the raw JSON Schema used to validate a road map file for this version of the road map library.

Types

type Author

type Author struct {
	// The Name of an individual or team which has contributed to this road map.
	Name string `json:"name"`

	// The Contact details for the individual or team, should a reader wish to contact them.
	// This may be an email address, IM handle or other method of contact.
	Contact string `json:"contact,omitempty"`
}

An Author is an individual or team which has contributed to the road map and which may be able to provide additional context if required.

func (*Author) ID

func (a *Author) ID() string

ID will return a deterministic identifier for this author which may be used to uniquely identify them.

type Deliverable

type Deliverable struct {
	// The Title provides a brief name for this deliverable.
	Title string `json:"title"`

	// The Description is a markdown formatted body of text which provides additional
	// context on this deliverable.
	Description string `json:"description,omitempty"`

	// The Reference is a URL at which additional information about the deliverable can
	// be found. This may be documentation, a tracking ticket or a PR.
	Reference string `json:"reference,omitempty"`

	// The Requirement specifies, using RFC2119 form, the impact that delivery has on
	// the milestone (MUST, SHOULD, MAY).
	Requirement string `json:"requirement,omitempty"`

	// The State of the deliverable may be one of TODO, DOING, DONE, SKIP.
	State string `json:"state,omitempty"`
}

A Deliverable is a concrete task which may be delivered as part of a broader milestone. Deliverables can state their RFC2119 requirement level to indicate how their delivery impacts the milestone.

func (*Deliverable) ID

func (d *Deliverable) ID() string

ID returns a deterministic identifier for this deliverable which is based on its title and reference

type Milestone

type Milestone struct {
	// The Title provides a brief name for this milestone.
	Title string `json:"title"`

	// The Description is a markdown formatted body of text which provides additional
	// information about the milestone.
	Description string `json:"description,omitempty"`

	// The Deliverables are concrete tasks which combine to achieve a given milestone.
	Deliverables []*Deliverable `json:"deliverables,omitempty"`
}

A Milestone is used to describe a high-level progress indicator for a team or project. It is composed of a series of deliverables and represents a shift in the delivered value at a level which can be understood by the business and customers.

func (*Milestone) ID

func (m *Milestone) ID() string

ID will return a deterministic identifier for this milestone which is based on its title and deliverables.

type Objective

type Objective struct {
	// The Title provides a brief name for this objective.
	Title string `json:"title"`

	// The Description is a markdown formatted body of text that which provides additional
	// context on the objective.
	Description string `json:"description,omitempty"`
}

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.

func (*Objective) ID

func (o *Objective) ID() string

ID returns a deterministic identifier for this deliverable which is based on its title and reference

type Roadmap

type Roadmap struct {
	// The Title is used to briefly introduce the road map to a reader
	Title string `json:"title"`

	// The Description is a markdown formatted body of text explaining the road map
	// and any context that a reader should have when consuming it.
	Description string `json:"description,omitempty"`

	// The Authors list provides the names and contact details for each of the individuals
	// or teams involved in defining the road map. They act as points of contact should questions
	// about the road map arise in future.
	Authors []*Author `json:"authors,omitempty"`

	// The Objectives list contains the high level goals that the team is working towards
	// and should inform both the content and prioritization of deliverables in each milestone.
	Objectives []*Objective `json:"objectives,omitempty"`

	// The Timeline lists important dates which are of relevance to the execution of this
	// road map. They are intentionally separated from milestones as we expect that milestones
	// are executed in sequence and might be delayed or accelerated based on external factors.
	Timeline []*TimelineEntry `json:"timeline,omitempty"`

	// The Milestones act as a series of high-level progress indicators. These allow a team
	// to visualize where they are on the road map without being overly constrained to the
	// specific execution.
	Milestones []*Milestone `json:"milestones,omitempty"`
}

A Roadmap describes a series of milestones and important dates which combine to outline a planned sequence of execution for a given project or team.

func Parse

func Parse(in []byte) (*Roadmap, error)

Parse will convert a provided input buffer into a roadmap structure.

func (*Roadmap) Validate

func (r *Roadmap) Validate() error

Validate will check whether the provided road map is valid according to the embedded JSON Schema.

type TimelineEntry

type TimelineEntry struct {
	// The Date associated with this timeline entry.
	Date time.Time `json:"date"`

	// The Title provides a brief name for the timeline entry to succinctly convey meaning to a reader.
	Title string `json:"title"`

	// The Description is a markdown formatted body of text providing additional context
	// on this timeline entry to any reader who needs it.
	Description string `json:"description,omitempty"`
}

A TimelineEntry describes an important date which is relevant to the road map. This may be a delivery date, quarterly milestone or any other point-in-time reference.

func (*TimelineEntry) ID

func (t *TimelineEntry) ID() string

ID will return a deterministic identifier for this timeline entry which is based on its title and date.