notheotherben
commented
3 years ago Let me know what you think of the following output (and if you're happy, we can call this done).
There are two output formats (simple and full) which cater to different Markdown renderers. GitHub only supports the simple one in comments like this, but the advanced one works fine for things like VSCode etc). They are shown as a screenshot (full) and inline Markdown (simple) below.
"Road map" Road map
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.
Authors
- Benjamin Pannell (contact@sierrasoftworks.com)
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.
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
We need to add a README file explaining the purpose of this project and giving some basic examples of its use.
DONE | Road Map
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
Put together a JSONSchema file describing the road map file format.
DONE | Publish Schema
Publish the schema file on schemas.sierrasoftworks.com so that people can reference it easily.
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
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
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
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
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
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
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
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
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.
asachs
It would be great if there was a way to render the roadmap document out to a markdown output format.