Markdown

I know, I know, why would you write your road map in YAML with Markdown text in it only to have it converted back into Markdown? Well, it turns out there are some good reasons (namely the other tools in this repo) but I'd also wager your final rendered Markdown probably won't look anywhere close to as good as this...

Usage

Prerequisites

Our Markdown generator is written in Go, so you'll need to make sure you've installed that on your machine. We recommend Go 1.16+ since it'll let you run the tool without needing to clone the repo or do any manual building.

Once you have Go installed, run the following to get the project and make the tool available to run.

# This installs the roadmap tool in your Go binaries folder.
go install github.com/SierraSoftworks/roadmap/tools/roadmap@latest

Conversion

To convert your roadmap.yml file into its Markdown representation, try running the following command. It'll write the result to your terminal, but if you'd prefer, you can write it to a file as well.

roadmap render md --in roadmap.yml

roadmap render md --in roadmap.yml --out roadmap.md

Frontmatter Support

If you're rendering your roadmap to a target which supports Markdown frontmatter, you can use the frontmatter-markdown format (aka fmd) to generate a Markdown file which includes frontmatter fields for the title, description and any other custom fields you might wish to provide. This is useful for integrations with tools like Hugo or Jekyll.

roadmap render fmd --in roadmap.yml --frontmatter 'weight: 10, tags: ["roadmap"]'

roadmap render fmd --in roadmap.yml --out roadmap.md --frontmatter 'weight: 10, tags: ["roadmap"]'

This will result in your Markdown file starting with the following frontmatter preamble (note that title and description are automatically populated from the roadmap's metadata if you don't specify them).

---
title: "Your Roadmap Title"
description: "Your Roadmap's Description"
weight: 10
tags: ["roadmap"]
---

Output

The output generated by this tool is a Markdown file which can then be rendered by any compliant Markdown renderer with HTML support enabled. It doesn't include any JavaScript and uses static, inline, styles on anything that needs it, so you don't need to worry about external dependencies.

TIP

In some cases you might need to generate Markdown which doesn't include inline styles and HTML elements. In this case, you can use the --simple flag to switch to a simplified Markdown mode which doesn't look quite as good but should work just about everywhere.

Rendered

Everything below the line here is the result of the Markdown renderer, enjoy 😉.

---

"Road map" Road map

Authored by

Benjamin Pannell

contact@sierrasoftworks.com

This is the planning road map for the SierraSoftworks/roadmap project. It acts as both the plan for implementing this tool as well as a demonstration of what a road map might look like.

One of the things you'll immediately notice about this file is that it uses Markdown for formatting of text and is designed around a structured YAML schema. The goal is to make this as easy as possible for humans to read and reason about, while also enabling powerful visualizations to be generated based on the content.

Important Dates

2021-04-21

Project Start

This is the day that the project was started.

2021-06-01

Demo Day

This is the scheduled date for the first demo of this project to a wider audience.

Objectives

We provide a single, universal, schema for high-level planning

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. The usefulness and applicability of this schema to real-world problem domains will determine whether anything else we do here is of value.

We provide official tooling for most common use cases

While the goal of having a single unified schema for planning is that it enables the development of tools that automate various aspects of planning, most teams are not going to adopt this if the fundamentals aren't already solved for them. This includes things like being able to visualize your road map in common formats, validating it against the schema etc.

We have exceptional documentation

Adoption of something intended to make planning easier is only going to be successful if it is easy to use, and a critical part of that is great documentation. Our goal is that someone with no familiarity with our tooling can ramp up and have an initial road map ready for use within only a few minutes.

Milestones

M1

Design and Planning

The design and planning stage is where we're figuring out how this project should work and, broadly, what kind of information we want to show on our road maps.

DONE

README MUST

We need to add a README file explaining the purpose of this project and giving some basic examples of its use.

DONE

Road Map MUST

We need to know what the road map file format looks like, so we'll get started with an example road map to kick the tyres.

M2

Road Map Schema

Once we know how we want a road map file to look, we should put together a schema for the file. This will allow us to document the file structure and provide a first class editing experience to people using it.

DONE

roadmap.schema.json MUST

Put together a JSONSchema file describing the road map file format.

DONE

Publish Schema MUST

Publish the schema file on schemas.sierrasoftworks.com so that people can reference it easily.

Read more →

M3

GraphViz Renderer

The first output format we would like to target with this project is GraphViz. It isn't necessarily the most beautiful or powerful output format, but it is a simple target to demonstrate functionality and give us a useful proof of concept.

Most importantly, it sidesteps the issue of us figuring out how to present road maps because we have some good examples to build off of.

DONE

GraphViz Generator SHOULD

We need to write a generator which converts a road map YAML file into an appropriate GraphViz DOT file which can then be rendered by any GraphViz renderer. This output format might only support a subset of the total Road Map schema's features initially.

M4

Documentation Website

The next step here is to put together a website explaining how to use road map. Initially this will be just a documentation website, but we should design with the expectation that we will be adding an in-page renderer for road maps and eventually an in-page editor experience as well (likely with Monaco or similar).

DONE

VuePress Website SHOULD

It makes sense for us to bundle the documentation and the editor in a common website. The easiest way for us to do this will likely be to build on VuePress 2 given our previous experience with it and Vue.

This should then be published somewhere (presumably roadmap.sierrasoftworks.com).

Read more →

DONE

Documentation SHOULD

Let's write some documentation explaining how to use road map and publish that on the website.

M5

Web Renderer

GraphViz is great, but being able to see things like the description of your deliverables and their current state is something that most users are probably going to find quite useful. Pair that with a need to make tinkering and experimentation easy and there are few things better than an interactive website to show your road map.

The goal here is to produce something which is easy and pleasurable to use, which shows your road map in a format which can be understood and makes interacting with it as low-fuss as possible.

DONE

Web Renderer MUST

The most important part of this milestone is the development of a web based renderer which can present a road map file. This renderer is going to form the basis for our user flows, including acting as a realtime preview for the editor and a final output for the repository viewer.

DONE

Editor SHOULD

Making it easy for people to experiment with Road Map is going to be an important part of getting them to use it. Providing an in-page editor which they can toy around with and instantly see results is a great place to start.

DONE

Repo Viewer SHOULD

Not everyone wants to host their own website to show off their road maps, so having a permalink which will always show the latest road map from their repository (using the GitHub API) is probably a great way to reduce friction.

TODO

File Viewer SHOULD

For those poor souls who don't use GitHub as their source control provider of choice, we should let users view a road map file by dragging and dropping it into the viewer.

TODO

Renderer Package MAY

Some teams might want to host a version of the renderer on their own website, in which case we should provide them with a package that lets them use the Road Map web renderer from within their Vue application.