Managing blockchain projects with user stories
Part II — Writing user stories
This is the second of a three-part blog describing a way of applying the agile methodology for blockchain projects. In this part, I’ll discuss a technique for writing good user stories using a hypothetical blockchain project for illustration.
There is no special technique for writing user stories for blockchain project. The same technique used for non-blockchain projects applies to blockchain projects too. I recommend the approach describe by Roman Pichler’s “10 tips for writing good user stories” and “From personas to user stories” as a technique for writing good user stories.
To illustrate the application of the Roman Pichler approach, I’ll use two hypothetical blockchain scenarios.
Scenario 1 — A scenario involving end users of a blockchain-based solution[1].
A company call Fox Private Limited (FPL) plans to go public but is currently awaiting approval to list its shares. In the meantime, FPL has decided to issue security tokens in lieu of the listings of it shares. As soon as the shares are publicly listed, owners of security tokens can then exchanged their tokens for FPL shares and no new tokens created.
FPL plans to list with 1000 shares, of which 10 shares are already allocated to Mr Fox, the owner of the FPL. The rest of the unassigned shares are to be held by FPL itself.
In some future date, let’s call it (
L) date, FPL will list its shares. 50 days (L-50) prior to the listing, FPL created tokens that have 1:1 relationship with the shares to be listed.On
L-50FPL started selling its tokens to the public via its website. Any member of the public can buy tokens minted directly by FPL. Paul, an investor bought 1 new token from FPL directly onL-50.An exchange, let’s call it the “Exchange”, a separate organisation from FPL, was setup to enable investors of FPL’s token to buy/sell amongst themselves. The “Exchange” is not permitted to mint token and can only facilitate trade in tokens that are already in circulation amongst investors.
On
L-49, Mr Fox offload 1 token to John and, in effect, promising to sell one of his own FPL shares on listing dateLto John.On
Lday itself, FPL stop minting tokens. Investors who bought and own tokens prior to L day, can claim shares directly from FPL unassigned pool of shares.
The first step in creating user stories representing this scenario is to identify the personas. From the scenario, you should be able to identify from the descriptions of the scenarios key personas (i.e. Mr Fox, Paul and John). We could start writing user stories associated with these personas. However, to start at this level, we could be in danger of losing sight of the forest from all the user story trees, so to speak.
As per recommendation by Roman Pichler, let’s start with identifying epics — i.e. user stories that focus on types of personas or persona role. This is an exception to the suggestion I made in Part I of this blog but necessary to give us a big picture view. For this scenario, we have identified three epics:
- Investors registering to enable trading in FPL Tokens;
- Investors trading FPL Tokens
- Investors converting FPL Tokens to shares.
Consider the epic related to registration, I recommend recording the epic as shown in Figure 1. An epic will include a user story from the perspective of persona role (i.e. investor) and the personas associated with this epic. The user story aspect of an epic should be very broadly specified. What do we mean by “broadly specified”?
Broadly specified means writing your epic stories to reflect the intention of one or more activities to be performed by types of users. For example, in the blockchain system, in order for anyone wishing to transact and be known in the system, you typically create private/public keys wallets. If your epic story were to speak of creating private/public keys that would restrict your choice of identifying yourself in the blockchain system. If you took a step back and try to imagine, what the intention of wallets are, you will then be able to see that the intention is effectively to register oneself. Hence, it is better to say to “register” than to say create a private/public key wallet.
When we refine the Epic, we can start to reflect on more precise ways of “registering a user” to enable transaction on a blockchain. It is worth noting that a private/public key wallet is only one way of facilitating a transaction. There are other ways too such as the use of a certificate authority.
Having identified an epic, we then proceed to refine it into a series of user stories reflecting the perspectives of each persona. This means a persona, such as Paul, as illustrated in Figure 1, could be interacting with our proposed product in different ways. To ensure that different perspectives are represented, we would capture in multiple user stories (see Figure 2 and Figure 3).
Figure 2 and Figure 3 are more concise than the parent Epic. However, it may not be concise enough for you to decide the tech you would offer. Take Figure 3 as an example; it simply states “use a trusted certificate authority”. It does not indicate how Paul, the persona, would interact with the certificate authority.
There are two options:
- one is to refine the user story but you should avoid making the story too verbose;
- or, the other option is to append with a context such as acceptance criteria as shown in Figure 4 or appending some kind of user interaction diagrams, whichever medium you find most expressive for you (and your team).
Assuming your story is concise enough for the team, my recommendation is to follow the example of appending more details as shown in Figure 4.
Repeat the process of identifying epic, then refine into user stories targetted at personas.
Scenario 2 — A scenario involving a developer needing a tool to help her debug her chaincode for a Hyperledger Fabric based blockchain[2].
Tabitha, who is a skilled DevOps engineer, is tasked with writing chaincode to support the use case presented in scenario 1.
She wants to be able debug the chaincode in a Fabric network, capable of running on her Mac, that closely resembles a production setup.
To do this she has to create a series of bootstrap cryptographic keys and genesis block, create Hyperledger Fabric channel, and, orchestrate Fabric certificate authorities orderers, peers and hooks to upload chaincodes.
In this scenario, the smart contract that Tabitha is building is a part of a deliverable for Scenario 1. In this case, the smart contract is not intended as delivery to Tabitha, it is not necessary to express this piece of work in the form of a user story targetted for Tabitha. Simply express it as a list of tasks to be done and append it to the user story (see Figure 5).
However, should the stakeholder of the project with deliverable for Scenario 1 feels that there is business value to build tools to help Tabitha and her peers, then express the needs of these users should be expressed form of user stories such as an epic as shown in Figure 6.
I would recommend for the project to be managed as a separate project or backlog from the one intended for Scenario 1. This is because the deliverable for Tabitha and her peers have totally different imperatives than the deliverable for Scenario 1.
To summarise when writing user stories, I recommend you follow Roman Pichler approach. Start with writing Epics to give you a broad overview of the features of the product that you wish to deliver. Then refine the Epic with user stories targetted at identified personas.
In a relatively big, project you will find that you need to create many Epics and user stories. In many cases, many find yourself absorbed with deciding if sufficient Epics have been created or if user stories have been sufficiently refined or written with sufficient precision. There is a danger that you could so paralyse with user stories refinement that you can’t even start to build your product.
In Part III of this blog, I’ll be presenting a way of managing user stories based on lean startup and agile principles, with an emphasis on avoiding analysis-paralysis syndrome (i.e. too much focus on writing and refining user stories not starting the project).
Note:
[1] This scenario has excluded details such as regulatory constraints purely to support the discussion intended for this blog.
[2] In this scenario, we have jumped significant steps and came to the conclusion that we’ll be using Hyperledger Fabric. This is only an arbitrary choice, intended to illustrate a use case. Another blockchain platform could be used. It is also beyond this blog or necessary for current discussion to go into details the architecture of Hyperledger Fabric. Should you want to have more information, please refer to official Hyperledger Fabric documentation for details.
