opendev/storyboard
Code Issues Proposed changes

Clarify the rationale for StoryBoard's unique design

Browse Source 
Explain a bit more about the nature of our open community, and make
connections between this and StoryBoard's unique feature set.

Move the REST API section to the bottom, since this is the least
user-facing aspect and more of an implementation detail.

Also tweak the wording from the style in the original blog post, to
reflect that this is now documentation of a project which is no longer
brand new.

Change-Id: I0a9cac50f3d6d5db13b3d820f0212632cc048454
This commit is contained in:
Adam Spiers 2019-05-07 17:00:12 +01:00
parent a25b54ad7e
commit 24f0187925
1 changed files with 104 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
doc/source/gui/theory.rst
View File

@ -2,67 +2,82 @@
Things that StoryBoard does differently
=========================================
StoryBoard has been custom-designed to support collaboration within an `open
community <https://governance.openstack.org/tc/reference/opens.html>`_
with the following characteristics:
- The community manages a large number of projects, and some
initiatives will span multiple projects.
- There are a variety of sponsors; no single organisation or person is
in control of the community's direction.
- Everyone is equally empowered to contribute.
- There are many stakeholders, who need to track diverse sets of
requirements for each project.
- Even when requirements overlap, priorities can differ widely.
Consequently StoryBoard has several features built specifically around
these needs.
If you've been using Launchpad on your project, by now you're probably
aware of its norms and idiosyncracies. It can be hard to envisage
different ways of doing the same tasks when thinking in terms of
things that are possible in Launchpad, so this post aims to give an
overview of some of the interesting new features in StoryBoard that
things that are possible in Launchpad, so this document aims to give
an overview of some of the interesting new features in StoryBoard that
don't have a Launchpad equivalent.
StoryBoard has been custom designed to fit the OpenStack use-case, and
so has several features built specifically around the OpenStack
community's needs. This post explains some of the key new things, so
that you can get familiar with the terminology, and construct
workflows that suit you -- hopefully by the end, you'll be as excited
as we are!
The REST API
============
Moving beyond universal priorities
==================================
StoryBoard has been developed with an API-first approach. What does
this mean? Well, at its core, StoryBoard has a python API. This then
plugs into a database, and can get information from it (or transmit
information to it). The StoryBoard API can then be accessed from
various clients, so that users can interact with some given database.
In StoryBoard, it's possible for different people to say 'this is a
priority for us', so that a task can have different priorities,
tailored to different audiences.
This means StoryBoard's features are first built on the API side, and
are then expressed in various clients. You can do more in the API than
in any given UI, since the UI just expresses the API.
So, why is this useful?
Why does that matter?
Traditional bug / task trackers have often modelled the concept of
priority as a single, shared attribute field. For example, anyone
could change a task's priority, and this would be seen by everyone
viewing the task. Typically there has been no way to say 'you can
only change this priority if you have discussed this on IRC and it has
been agreed among the project team', etc. This has meant that people
with no context could alter global priority of tasks. Also, two
different groups might prioritize tasks differently, and this could
result in long prioritization sessions, where the real question was
'whose priorities matter most?' (and often the answer was 'it depends
on who the audience is', so these arguments would result in a
stalemate).
Custom scripts! Custom UIs! If you can express it in a script, you can
fetch the data from StoryBoard. You don't have to rely on features in
any current UI if you have a niche request, and it's possible to build
your own new UI (or dashboard) if you want. You can also get info from
the commandline on the fly with a tool like curl.
So, StoryBoard provides a way to say 'this task matters to *me*' or
'this task matters to *my team*', without trying to force that point
of view on everyone else. We use worklists to express priority: if
you manually add tasks to a worklist, you can drag and drop them in
order of priority. This has the side effect that you can see how
prioritizing one task affects the priority of other tasks; you can
only have one item at the top, and putting anything high on the list
will push other things down. It is possible for others to subscribe
to the worklists of those individuals or teams whose priorities they
care about; then, whenever they browse to a prioritised story, they
will see if any of the tasks are on those lists, and what position the
tasks are on the list.
There are some docs to illustrate usage here:
Worklists have permissions, so it is possible to set up a project team
list on which items can only be moved by contributors selected by core
reviewers, etc. This stops everyone changing the priority of tasks
without discussion.
https://docs.openstack.org/infra/storyboard/webapi/v1.html
This is still relatively new, and we're excited to see how people use
it. We've lost some ease in assigning priority in favour of finer
grained representation of priority. In the past, StoryBoard did show
lots of different people's priorities, it just didn't offer any way of
tracking whose priorities were whose. So this makes things more open
and explicit. We hope to tailor the implementation based on user
feedback, and these are the first steps! :)
Moreover, as our API is generally RESTful, it's straightforward to
guess how to do things, and compatible with a lot of other tools with
minimal tinkering. Here are some sample, heavily commented scripts for
one simple example (commandline) interface, a python client:
https://review.openstack.org/#/c/371620/
There is also a much more fully-featured and interactive commandline
StoryBoard interface named boartty in progress over here, that jeblair
wrote on a plane:
.. image:: _assets/boartty-3.png
The long and short of it is, if you know how to display data from a
REST API, you can display data from a StoryBoard instance.
You can do some fun things with this. For example, you could use
pygame if you wanted to depict stories as moving platforms or
something (I have publically said I'll try this, so I guess I've got
to follow through at some point). On that note, if anyone feels like
hacking something up, please tell us; we'd love it. Our irc channel is
irreverent and procrastinatory. You can find us in #storyboard.
Worklists and Boards
====================
@ -116,49 +131,50 @@ description).
For documentation on how to create boards, add users/owners, etc
:doc:`that can be located here<boards>`.
Complex Priority
================
We already wrote a massive email on this, intended as a thorough
overview, so we are going to shamelessly copy and paste it here. The
crux is that in StoryBoard, it's possible for different people to say
'this is a priority for us', so that a task can have different
priorities, tailored to different audiences.
The REST API
============
So, why is this useful?
StoryBoard has been developed with an API-first approach. What does
this mean? Well, at its core, StoryBoard has a python API. This then
plugs into a database, and can get information from it (or transmit
information to it). The StoryBoard API can then be accessed from
various clients, so that users can interact with some given database.
Previously, StoryBoard allowed users to assign one priority to each
task ('high', 'medium' or 'low'). The implementation meant that anyone
could change a task's priority, and this would be seen by everyone
viewing the task. There was no way to say 'you can only change this
priority if you have discussed this on irc and it has been agreed
among the project team', etc. This meant that people with no context
could alter global priority of tasks. Also, two different groups might
prioritize tasks differently, and this could result in long
prioritization sessions, where the real question was 'whose priorities
matter most?' (and often the answer was 'it depends on who the
audience is', so these arguments would result in a stalemate)
This means StoryBoard's features are first built on the API side, and
are then expressed in various clients. You can do more in the API than
in any given UI, since the UI just expresses the API.
So, StoryBoard now has a way to say 'this task matters to me'. We use
worklists to express priority: if you manually add tasks to a
worklist, you can drag and drop them in order of priority. This has
the side effect that you can see how prioritizing one task affects the
priority of other tasks; you can only have one item at the top, and
putting anything high on the list will push other things down. It is
possible for others to subscribe to the worklists of those individuals
or teams whose priorities they care about; then, whenever they browse
to a story, they will see if any of the tasks are on those lists, and
what position the tasks are on the list.
Why does that matter?
Worklists have permissions, so it is possible to set up a project team
list on which items can only be moved by contributors selected by core
reviewers, etc. This stops everyone changing the priority of tasks
without discussion.
Custom scripts! Custom UIs! If you can express it in a script, you can
fetch the data from StoryBoard. You don't have to rely on features in
any current UI if you have a niche request, and it's possible to build
your own new UI (or dashboard) if you want. You can also get info from
the commandline on the fly with a tool like curl.
This is very new, and we're excited to see how people use it. We've
lost some ease in assigning priority in favour of finer grained
representation of priority. In the past, StoryBoard did show lots of
different people's priorities, it just didn't offer any way of
tracking whose priorities were whose. So this makes things more open
and explicit. We hope to tailor the implementation based on user
feedback, and these are the first steps! :)
There are some docs to illustrate usage here:
https://docs.openstack.org/infra/storyboard/webapi/v1.html
Moreover, as the API is generally RESTful, it's straightforward to
guess how to do things, and compatible with a lot of other tools with
minimal tinkering. Here are some sample, heavily commented scripts for
one simple example (commandline) interface, a python client:
https://review.openstack.org/#/c/371620/
There is also a much more fully-featured and interactive commandline
StoryBoard interface named `boartty
<https://opendev.org/ttygroup/boartty/>`_ written by Jim Blair:
.. image:: _assets/boartty-3.png
The long and short of it is, if you know how to display data from a
REST API, you can display data from a StoryBoard instance.
You can do some fun things with this. For example, you could use
pygame if you wanted to depict stories as moving platforms or
something. On that note, if you feel like hacking something up, the
Storyboard team would love to hear from you! Come and say hello on
the ``#storyboard`` channel on Freenode IRC.