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 byBenjamin 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-21Project Start
This is the day that the project was started.2021-06-01Demo 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
M1Design 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.
M2Road 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.
M3GraphViz 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.
M4Documentation 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).
DONE
Documentation SHOULD
Let's write some documentation explaining how to use road map and publish that on the website.
M5Web 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.