Functional requirements, content requirements, and CUJs

Question

I'm working on a project to build a new documentation site that will host documentation about a service we maintain. We're building this documentation site from scratch and writing the API documentation itself from scratch. I've started on trying to define the CUJs (critical user journeys) and requirements for this project.

At first, I created a list of CUJs, and for each CUJ, listed the relevant requirements under that CUJ. So, for example:

• CUJ 1: As a user, I should be able to browse/search among all API endpoints.

  • Req: The site should provide an exhaustive list of all API endpoints as links to their documentation pages.
  • Req: The site should provide a free-form text input to search for API endpoints by name.

• CUJ 2: As a user, I should be able to view documentation on an API endpoint.

  • Req: The site should provide the endpoint name.
  • Req: The site should provide a short description of the endpoint.
  • Req: The site should provide an example request and response.

I've realized that some of my requirements have to do with the functionality of the site (i.e. those within CUJ 1) while others have to do with the content of the site (i.e. those within CUJ 2). For example, the associated functional requirement for CUJ 2's requirements might be "The site should allow maintainers to write documentation on API endpoints." This difference is somewhat confusing to developers who only care about the functional requirements... as that's specifically what they need to implement for the site.

Have others encountered this before - and if so - how did you handle it? Thanks!

Answer 1

I do not know what CUJ is (or FR), but I will do my best to answer you.

1. Learn how to write requirements, in general. Example: "should" is not a good word for a requirement, "shall" is preferred.
2. Generally speaking, there are many types of requirements. Functional, architectural, test-related (yes, test cases are actually requirements), legal requirements (dictated by the laws of the country), internal regulations also generate requirements, national and international standards, commercial, schedule-related requirements etc.
3. The first phase, as you already noticed, is a brainstorming phase. Therefore, any requirement "is a good requirement". In a later phase, you will start refining, sorting, grouping and improving the requirements. And adding many more requirements.

This difference is somewhat confusing to developers who only care about the functional requirements...

The developers, as well as everybody in the project, must be trained about what requirements are and how they should be handled. And "dot not care" is usually a good reason to lose a job ;)

Bottom line, not only that you will have functional requirements and non-functional requirements, but you must have back-end requirements, as well as front-end requirements. Some of them will be even about reliability, redundancy, the management of updating / upgrading the system (site)...

Many times, the job of writing the requirements is overwhelming for only one person, and big projects have entire teams dealing only with requirements.

I wish you luck, since it seems that your company is not yet really prepared for such a job.