Features How-To's

Manage Product Requirements with YouTrack Knowledge Base

Read this post in other languages:

Lots of development, marketing, product, and project teams are using YouTrack to deliver great products. This requires an effective process for managing product requirements. The typical process involves creating user stories and epics, using a project overview with Gantt charts, tracking feature requests publicly and internally, fixing bugs, and collaborating with other teams on issues.

Now, there is another way. You can manage product requirements right in Knowledge Base, using YouTrack to create, manage, and track your product requirements documentation.

Let’s see how this works!

Why do you need a product requirements document?

If you’re a product owner, you’re launching a product, or you’re a part of the team working on a project and want to know what the product does and how it works, then the Product Requirements document will often be your go-to source of information.

Product requirements describe and define your product’s general purpose, behavior, features, and functional characteristics from the very beginning of the project, before the product itself materializes. But simply writing these things down is not enough. The product vision often changes over time, and product requirements undergo multiple adjustments and modifications. It can often take a lot of time to ensure your product keeps up with the latest requirements.

This is why a well-configured requirements management process is important. When organized correctly, it can help you keep track of any important points and maintain control over the changing requirements.

Here are a few things you can keep in mind to manage your product requirements smoothly.

Collect all sources of your future requirements

Starting a project from scratch can be quite challenging. Make sure to collect everything that relates to your future product – research, feedback from potential users, and any planning or brainstorming you’ve already done. At this stage, it works to just throw together everything but the kitchen sink. You will have a chance to filter out the fluff and keep the important things later.

Consider the following sources of requirements, depending on your process:

  • Current materials related to your business strategy and product goals.
  • Product team input.
  • Results of studies such as strategic research or product-market fit analysis.
  • Feedback from potential users. Talk to your support team – chances are they have a lot of useful information to share.
  • Competitor analysis. Others may have already run into some pitfalls that you can try to avoid.
  • To-customer meetings such as interviews, surveys, and demos.
  • Your public issue tracker, if you have one.
  • Your own vision of how the product or its feature should behave. Don’t underestimate your gut feeling!

The main goal at this stage is to collect everything in one place. Create a draft in YouTrack Knowledge Base and link your documents using one or more of the available options: embed Google documents with research studies, paste links to issues with user feedback, and attach files with your product strategy analysis.

Now that we have collected as much we could, it’s time to sift through the requirements and make them easy to manage.

Here comes the first draft

There are hardly any standards or rules when it comes to formulating product requirements. But we can gladly share some practices that have worked for us and helped us maintain a shared understanding:

  • Briefly describe the general goal of the product or feature.
  • Point out the responsible peers – so that it is immediately clear who the point of contact is in each main phase (such as QA or design).
  • Specify the target release or deadline – so that all team members are on the same page when it comes to the project’s scope, schedule, and time estimations.
  • Link corresponding epics or user stories – to keep a connection between the requirements and the actual development (we’ll cover epics in more detail later).
  • Determine the main points of the design, infrastructure, and behavior specifications.

Try to keep the ideas simple and straightforward. Anybody should be able to understand them on the first pass. Use tables and ordered lists to structure this information well.

Use the structure, Luke

Now it’s time to make the requirements neat and easy to navigate.

Full-text search can save your users when they don’t know where exactly to look – they just have to enter a keyword and browse the matching articles. However, let’s not force them to resort to searching, and instead make sure anyone can navigate through the requirements easily to find what they are looking for.

A clear tree-view structure can help you avoid repetitious or contradictory requirements, and it can help the reader find relevant articles quickly. It’s normal at this point to have a single structure level – the product requirements document itself, plus some related papers with strategic materials. However, as the product is developed, this structure will likely grow into something much bigger as it incorporates new materials, such as insights from customer interviews, conclusions from team meetings, and more. A good practice here is to maintain a clear structure from the very beginning, even if it seems at first like you won’t need it at all. For example, you can create dummy sub-articles for documents you expect to be added later, in order to consolidate the structure.

Next, you can move your requirements articles between different page trees and build a hierarchy that will meet your organization’s needs.

Time to collaborate

Ready to hear other opinions and points of view? Encourage your teammates and stakeholders by mentioning them in comments so they can join the discussion. Give contributors editing permissions so they can add their suggestions right on the spot, or keep the conversation in comments to make the discussion more transparent. You will be notified about every single change in any article.

It is important to involve the right people at the right time. For example, you may want to organize a meeting where all the stakeholders can review the requirements and discuss any potential concerns face to face.

There are several criteria a requirement must meet to be considered “good”: it should be concise, understandable, verifiable, consistent, and feasible. Surf your articles and update the requirements if necessary. It’s a good practice to establish a uniform way of marking each requirement that has been reviewed and approved, for example, by leaving a corresponding comment or adding a note to the table of essentials.

We also recommend keeping the results of your meetings – also known as meeting minutes – in dedicated sub-articles. This will help you recall what topics were discussed, what decisions were reached, and what questions were postponed.

Be agile (or don’t)

Depending on your process, you may expect your product requirements to change dynamically throughout the course of development, or you may expect changes to be formalized before each new stage of development begins. If changes are expected to happen throughout the development process, you’ll need to maintain a shared understanding of tasks at all times. If changes are made before a new stage of development begins, the requirements have to be approved with all the involved parties before implementation begins.

When practising an Agile process, it’s best to adjust the requirements as soon as a change occurs. This means you need to keep abreast of all the latest changes. We recommend conducting customer interviews after each iteration to make sure you’re still on the same page. We also suggest paying attention to backlog prioritization to make sure the most important things are on top. What’s more, don’t do these things alone – instead, involve the appropriate team members in discussions and customer meetings.

If you adhere to the Waterfall model, our recommendation would be to conduct several sessions to review the product requirements, inviting all relevant parties to participate, before moving to subsequent stages of development. This will help you avoid contradictory requirements and make sure everyone is on the same page.

Whichever process you follow, you will always be able to review and restore any of the previous versions of your pages.

Complete the story

Ready to start the implementation process? Use YouTrack issue types and links to create epics and decompose them into smaller tasks for your team.

Transforming your requirements into actual features and issues is a crucial step in the development of your product. At this point, you might realize that some of the requirements need to be reviewed and adjusted once again – and that’s fine. We recommend performing multiple review iterations to make sure the requirements are as close to reality as possible.

For waterfall processes, pay attention to another YouTrack planning feature – the Gantt chart. Gantt charts consider your possible start dates and dependencies between tasks and help you estimate project deadlines.

For agile processes, try the YouTrack Agile Boards feature with its handy big-picture view that displays all your epics and decomposed tasks on one screen. While an epic may represent a whole feature, tasks should be small enough to be completed in one to three days. Prioritize tasks, set up dependencies between them, and track the progress right on your board. We believe this is one of the most effective ways to stay fully synchronized with your product.

Form a backlog from your tasks (reorder them manually to prioritize them in order of importance, if need be) and embed it into the requirements page by copying and pasting the search URL. The backlog will be expanded right in the article to save you the hassle of constantly switching between the tracker and the knowledge base.

Venture forth and develop

We hope these tips will help you set everything up in a way that works for you and ultimately deliver an awesome product.

We have a few ideas about how to make YouTrack’s Knowledge Base even better. But what do you think? Let us know so we can shift our own product requirements in the right direction and ensure the best possible experience for you!

Your YouTrack Team