-
Notifications
You must be signed in to change notification settings - Fork 5
/
roadmap.yml
178 lines (157 loc) · 8.21 KB
/
roadmap.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
title: '"Road map" Road map'
description: |
This is the planning road map for the [SierraSoftworks/roadmap](https://github.com/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:
- name: Benjamin Pannell
contact: contact@sierrasoftworks.com
# The timeline allows us to highlight important dates on our road map. These are intentionally separated
# from the stages as it is expected that the delivery of stages themselves occur based on their dependencies
# and that the specific delivery dates may shift as a result.
timeline:
- date: 2021-04-21
title: Project Start
description: |
This is the day that the project was started.
- date: 2021-06-01
title: Demo Day
description: |
This is the scheduled date for the first demo of this project to a wider audience.
objectives:
- title: We provide a single, universal, schema for high-level planning
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. The usefulness and applicability
of this schema to real-world problem domains will determine whether anything else we do here is of
value.
- title: We provide official tooling for most common use cases
description: |
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.
- title: We have exceptional documentation
description: |
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:
- title: Design and Planning
description: |
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.
deliverables:
- title: README
state: DONE
requirement: MUST
description: |
We need to add a README file explaining the purpose of this project and giving some basic examples
of its use.
- title: Road Map
state: DONE
requirement: MUST
description: |
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.
- title: Road Map Schema
description: |
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.
deliverables:
- title: roadmap.schema.json
description: |
Put together a JSONSchema file describing the road map file format.
state: DONE
requirement: MUST
- title: Publish Schema
reference: https://schemas.sierrasoftworks.com
description: |
Publish the schema file on [schemas.sierrasoftworks.com](https://schemas.sierrasoftworks.com)
so that people can reference it easily.
requirement: MUST
state: DONE
- title: GraphViz Renderer
description: |
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.
deliverables:
- title: GraphViz Generator
description: |
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.
requirement: SHOULD
state: DONE
- title: Documentation Website
description: |
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).
deliverables:
- title: VuePress Website
reference: https://vuepress2.netlify.app
description: |
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](https://vuepress2.netlify.app)
given our previous experience with it and Vue.
This should then be published somewhere (presumably roadmap.sierrasoftworks.com).
requirement: SHOULD
state: DONE
- title: Documentation
description: |
Let's write some documentation explaining how to use road map and publish that on the website.
requirement: SHOULD
state: DONE
- title: Web Renderer
description: |
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.
deliverables:
- title: Web Renderer
state: DONE
requirement: MUST
description: |
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.
- title: Editor
state: DONE
requirement: SHOULD
description: |
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.
- title: Repo Viewer
state: DONE
requirement: SHOULD
description: |
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.
- title: File Viewer
state: TODO
requirement: SHOULD
description: |
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.
- title: Renderer Package
state: TODO
requirement: MAY
description: |
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.