Service Portal Stories: tips for success (part 1)
As an architect, I often find myself working with my teams to fine-tune stories that the client will approve and the developers will use to direct their work. I’ve noticed that often times there is little guidance to direct the creation of well-built stories for the design-heavy front-end work of Service Portal. This is the first part of a few articles I’ll be writing to review some strategies that will help set you and your team up for a smooth Service Portal implementation.
Gathering requirements
Before you can write the stories, you have to know the desired outcome. Even for small Service Portal setup projects, I recommend a dedicated two-hour session to hammer out the goals and requirements specific to the front-end experience. This can branch out into separate, deep-dive sessions for design, personas, or custom functionality if needed, but this is our starting point. I always recommend including the developers that will build your portal, the designers that will design it, and the architect directing the work in these workshops, so they can ask questions and explain the features and functionality. Usually, my workshops include the following:
Establish the current state: Your first goal is to get a good understanding of the current setup used by the client’s users for self-service. Ask them to show you their existing self-service, whether it’s in ServiceNow or on another platform. Discover what they like about it, and what challenges they’re experiencing.
Establish desired outcome (future state): Next, set specific goals for what they hope the Service Portal implementation will give them. Key off of the likes and dislikes they mention when discussing their current state. These are the goals that all requirements should point towards.
Personas: Establish who is going to be using the portal. Are there different users with different views or permissions? Are we differentiating between external and internal users? For more complex projects, I always recommend a dedicated persona workshop to establish the details of each persona that will access the portal, including top pain points, needs, roles, and responsibilities. This list of personas may differ from the list of users accessing the platform UI, and you’ll want to clearly delineate the differences.
Basic configuration: Gather information regarding basic setup of the portal, including search sources, the URL slug, and login configurations. These questions give you the information you need to direct your development team to set up the overall portal and get it functional.
Functional requirements: This is the meat of the requirements gathering work. Using the information you’ve gathered thus far, show the client a functioning demo portal for the type of project you’ll be implementing (CSM, Employee Center, etc). Touch on each available widget, page, and feature to ask about how these items need to be configured to meet their users needs.
Design requirements: After you know what the portal needs to do to meet user needs, dive into how the portal needs to be designed. This can be as simple as setting up the branding colors in the theme to match a given color palette, or kick off an involved process with custom mockups. Is there an existing site or guidelines you need to “match”, or does your design team have more creative freedom?
Writing the stories
The roles on a project team are varied, including the project managers, the client, developers and architect. Each of these roles look to stories for a different purpose, and will have needs requiring nuance in the information presented. Pay attention to the details in your stories to ensure the right details are included. Below, I’ve included details I find helpful for both the client and the development team.
Define relevant personas. Usually, this appears in a beginning statement such as: “As a user/manager/case worker, I can [insert requirement here].” If more than one persona are relevant to the story, have a separate statement reflecting the requirement for each persona, to clearly show the differences in developed display and behavior.
Use plain language: As you write out details of the story’s requirements, avoid acronyms or technical jargon. The main description and acceptance criteria for the story should be clearly understood if read by non-technical project team members, especially your client.
Account for different use cases: The content of a Service Portal is dynamic in nature more often than not. In your workshops, clarify these differences to understand all of the different ways in which a user can interact with the developed solution. For example, if you’re gathering requirements for a list of records, include the desired state if the list has no items in it (are we hiding the list, or showing a “no items” message?), or 400 items (do we paginate, or only show the top five?). These details are especially important for designers, who will need to provide guidance as to how each of these different details display.
Include all relevant assets: This is essential for Service Portal work. Is there a style guide or mockups the developer should follow? They should be attached to the story or linked in the Acceptance Criteria. This goes for any other assets the developer will need to complete the task, including font files, images, and logos. Ask your client for these assets during your workshops, and note in the acceptance criteria what files are attached to the story, and how they should be used. Your team should not have to go hunting for assets. The story should provide them with everything they need to complete their work, whether that’s a link to a mockup or attached image files. For design related activities, access to brand specifications or even brand-aware contacts are a must.
Technical details: This is going to require support from your portal-savvy architect. Ideally, my BPC/BA has taken care of the above items as much as possible, and I just have to provide technical details and possibly a technical approach (below). The technical details should include any and all relevant technical information the developer will need to complete the work. This will vary from story to story, but some examples include:
Tables, configurations, and integrations serving as the source of the information presented in the Service Portal, be it a list of incidents from the incident table, or configurations for the “My Items” widget in Employee Center.
Roles, groups, and specific user criteria information for filtering and visibility of content.
Notes and links to the stories for related or dependent development work.
Existing widgets or functionality from which to base the required work.
Note that while your design team may not need to know what table a set of records may be coming from, it’s important to ensure they have enough information to put forward designs that make sense with the related data. For example:
Knowing what fields from a record need to be displayed, and the different shapes that data can take (long text fields vs. short, integers, dates, etc) are important to how that information will be laid out.
Related OOB widgets the design will be based off of gives your designer insight into how that widget should be designed (or what limitations to the design may exist).
Technical approach: This is where your architect will really shine. In some cases (such as for completely custom widgets or other complex functionality), the architect can advise a process for completing the work. This can include where to put relevant CSS, whether to place widget scripting in a separate script include, or how to configure a page layout. Especially for more junior developers, a technical approach can ensure best-practice implementation.
Moving forward
This has been an overview of the beginning of the story-writing process specific to Service Portal front-end experiences. These stories should include additional information for related visual elements, widgets, and use cases that some typical technical stories do not require for successful implementation. I hope you find this information helpful as you gather requirements and write stories for your Service Portal projects.
In my next article, we’ll take a look at how you can divide up these stories and get them prepped and ready for your development team to tackle, as well as a few tips to help ensure your team’s portal work is completed to meet (or exceed!) expectations.