frederikheld / usm.io

A lightweight solution to represent your backlog as a User Story Map and integrate backlog management into your development workflow by maintaining it in your repository side-by-side with your code.

usm.io

A lightweight solution to integrate backlog management into your development workflow and to put your backlog into the repository with your code.

What is it?

usm.io can render an User Story Map from a structured data representation into an interactive website.

The USM is defined in json format, that is complemented by Markdown or HTML to describe the contents of the cards in the map.

This makes working on your backlog as simple as possible, as you can use your well-known development tool and focus on the stories, while usm.io takes care of proper visualization.

Why use it?

usm.io is a different approach to backlog management as opposed to common backlog management tools, which have several disadvantages:

1. They store data separately from the actual code. So keeping the backlog in sync with the code is often tedious and taking a snapshot over your whole toolchain is difficult or even impossible.

2. They usually are very heavy on features. This comes in handy if you want to represent elaborate workflows, but it's a bit over the top if you just want to manage your backlog.

3. The only way to interact with them is a graphical user interface. But keeping your backlog tidy can be annoying if it involves a lot of clicking around and waiting for things to be loaded.

usm.io offers a lightweight approach to editing your backlog as code and keep it in the repository with your code.

Plus: it visualizes the backlog as an User Story Map wich gives you great transparency over your roadmap.

How to use it

usm.io comes as a npm package that you can install in your own NodeJS project:

$ npm install --save usm.io

You can now use it like this:

const Usm = require('usm.io')

const context = {
  inputDir: './input', // where to look for sources
  outputDir: './web', // where to put rendered pages
  cardsWebroot: 'localhost:80/usm' // your hosting domain and directory. If used locally: a absolute or relative directory path.
}
const mapOptions = { ... }
const cardsOptions = { ... }

const usm = new Usm(context)
await Promise.all([
  usm.renderMap(mapOptions),
  usm.renderCards(cardsOptions)
])

Please see the source code in the example(./example) directory for details mapOptions and cardsOptions.

For each rendering feature there's an asynchronous function that takes the input from the inputDirectory and writes the rendered output to the outputDirectory. They can be run concurrently.

If you're working in a team, a good practice is to integrate the generator into your build pipeline, have it run with each push to the main branch and publish the build results as a website. This way you can assure that the visualization of your backlog stays up to date with your repository and is accessible to everyone.

Run the Example

This repository comes with an example that shows how you can integrate the generator into your project. It also includes stylesheets and scripts that bring the generated html map to life. They are a good starter for your own project.

See example.

How to provide the input

See The User Story Map for details on how user story mapping works, the features of usm.io and how you need to structure your map to make it render correctly.

Contribute

I'm happy for any help with usm.io. If you would like to contribute, please look into the issues to see which new features are already in the backlog and which chores need to be done.

If you have a good idea for a new feature or improvement, feel free to file a new issue or submit a pull request.

usm.io's Issues

Keep Activities and Steps visible when the map is scrollend vertically

As a map most probably has to be scrolled vertically, it would help the users to orient themselves better to see the Activities and Steps all the time.

Possible solution: Make them sticky at the top of the screen (like fixed rows in Excel)

Allow aliases for keys in usm.json and card.json

This visualization tool is designed for the use case "User Story Mapping" and therefore all keys follow the common naming in User Story Maps.

The visualization methods works great for other kinds of mapping as well though. For those kinds of mapping the naming might be different. So it would be great to use different names for the keys in usm.json and card.json.

Possible solution:

This might be done in a config file that defines the mapping between the original name and the alias.

Example:

activity=myaliasforactivity
step=myaliasforstep
story=myaliasforstory
story.description=details

Add option to highlight specific cards in map by adding a pre-defined label

Adding labels to cards would help to group them, e. g. to indicate in which state of the workflow they are.

Therefore labels should be rendered as css classes so they can be styled with special background or border colors or other kinds of highlighting.

To allow styling and to add an appropriate legend, they might need to be limited to a pre-defined list that could be pre-defined like releases.

But opposed to releases it should be possible to add multiple labels to a card to highlight different aspects. Styling has to make sure that different aspects don't overwrite each others.

Provide useful error message if usm.json or card.json is malformed

Example: If "stories" is missing in usm.json, error says "UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'length' of undefined".

Solution: This message should be more specific and help to find the error. E. g. "Field 'stories' missing in ...". It should also help to fix/avoid the error, e. g. "Field 'stories' is mandatory for a step."

Also make renderer more flexible. This specific example shouldn't lead to an error at all. It should be allowed to leave fields undefined.

Keep Releases visible when the map is scrollend horizontally

As a map most probably has to be scrolled horizontally, it would help the users to orient themselves better to see the releases all the time.

Possible solution: Make them sticky at the left side of the screen (like fixed columns in Excel)

Add option to make cards more searchable by tagging them

Tags could be introduced to summarize the contents of a cards for better searchability or grouping according to topics. As opposed to labels, it should be able to create tags on the fly as they will have no other functionality than make the card searchable.

Navigation from Card package back to the Map

Right now the users needs to remember to go back in the browser history to get back to the map. Otherwise they are lost. A "back to map" navigation element in the Card website would solve that.

Make structure of test suites more suitable for documentation

There are several issues with the test suites

• Levels on which testing is done aren't clearly defined. I would at least like to have the following:
  • Behaviour tests: Test the features from the user perspective. Those should be the tests with the main focus on because they serve as documentation! Issues: Some test suites have a bad structure that makes them difficult to read --> re-structure to make it suitable as end-user documentation!
  • Integration tests: Whenever modules have to interact. Can help to define the interfaces between modules. Issues: Right now we don't have much of those and they are somehow mashed into the other tests. This reflects in bad interfaces between some modules --> Add dedicated integration tests to help to refactor module interfaces!
  • Unit tests: for complicated algorithms (e. g. the generation of the releases css). Issues: We don't have any of those yet. Most of the stuff is covered by behavior tests, but this somehow makes it difficult to keep the layers of granularity apart. On the other hand we don't need to test everything twice just for the sake of it --> cover algorithms that aren't tested at all yet. Best case would be to put those into their own libraries which then can be integration tested... IDK.

Acceptance criteria for Story Cards

Besides the title and description, Story Cards should also have a field to add a list of acceptance criteria that will be rendered as such automatically.

Show Card's title in the head of its website

As the title says. Maybe with a leading generic portion:

Project name: "My USM"
Card title: "Feature Foo"
Generated website title: "My USM > Feature Foo"

This would require to specify the project name in usm.json.

Remove duplication in Usm and sub-classes

Remove duplication: There's a lot of duplication in all the classes that form Usm. There should be one generic class for containers and one for card representations. All the specific classes should extend one of those two basic classes.

Improve test coverage / feature documentation

• Some lines are not covered at all yet. Run npm run-script coverage to see which.
• Some features aren't tested yet, e. g.
  • the order of the given css links in the renderOptions defines the order in which the stylesheets tags are rendered. This is how JS does it (elements in an array have an order), but it isn't documented as a feature for the user. Documentation of such features should be done with appropriate tests.

Deep Links to cards

It would be nice if the URL would change (e.g. with an additional #mycard) when I have a card shown so that I can send this URL around and have people see what I see.

Add search feature

AS user
I WANT TO find contents in title, description, card text and tags
SO THAT I don't need to click trough all cards to find something (or find out that it doesn't exist).

Make renderer more forgiving

Renderer should be more forgiving regarding missing fields that actually should be optional.

Example:
Right now the renderer complains about missing "steps" or "stories" fields in usm.json. So even if you don't want to provide any steps or stories yet, you have to add the field and fill it with an empty list. This should not be necessary!

Does it work offline?

From the description in the README.md it is not clear whether the tools works offline or using an online service on Internet. It would be nice to add this information to the README.md

Make map draggable for scrolling

As a map usually becomes very large, users need to scroll a lot. This is tedious with classic scrolling through mouse wheel or scroll bars.

Therefore it would be nice to be able to just drag the map around.

Avoid confusion of cards: Do not allow the same title multiple times

I guess it should not be allowed to use the same title multiple times.

Imagine two cards with the same title. As long as each of them stays in their Step, you can distinguish them from each others. But usm.io encourages to move cards around and as soon as you put them in different steps, you don't know which is which anymore.

For the deep links feature this would lead to the technical problem, that the running number will most probably be added following the order of the cards in usm.json. If you move them around, the order might change and with it the deep-link will switch between cards :-P

I guess the technical issue could be solved somehow, but it would still be confusing for the user to allow the same title more than once.

Originally posted by @frederikheld in #10 (comment)

Header and footer templates for Map and Cards

Right now the generated websites consist only of contents. Map and Cards look like totally independent things.

There's some optical frame missing, that shows that those parts belong together.

This is best done with html header and footer snippets that provide all parts that are missing to make the rendered markup a full website (right now this is generated inside the generator).

The header and footer would also allow to add navigation elements and to display information about the app.