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!