Doubt defining functional requirements

Question

I'm trying to derive the functional requirements from a use case but I'm with some doubts.

The use case is about create a new post and it is presented below. For example looking to the pre-conditions one functional requirement could be:

When a user submit his credentials and they are valid, the system shall initiate the session of this user

It is correct? I read that a functional requirement can be written in the user or system perspective. In the case above it is in the system perspective, in the user or both? Because it has "when a user..." and then "the system shall...".

And for example in the step number 1 of the main flow what could be a functional requirement for this? I write this 2 options below but I don't know if it is correct, because I don't know if it should be written in the user or system perspective. For example in the user perspective:

The admin shall be able to fill and submit the information relative to a post.

Or in the system perspective:

When an admin fill and submits the post information, the system should store in the database that information.

Can you help understand better how to define the functional requirements properly in the example?

The use case is this:

Title: Create Post

Ator: Administrator

Pre-conditions: The administrator has a session initiated in the system.

Trigger: The administrator indicates that he wants to create an event.

Main flow:

1- The admin fill the information relative to title and message

2- The system presents a preview of the post in the page

3 - The admin submits the filled information, and the admin can just save the post information or publish the post

4- The system validates the information inserted by the admin

5- If the admin just save the post the system saves the inserted information in the db and informs the user that the post was saved. If the admin publish the post, the system saves the inserted information in the db,publish the event, and informs the user that the post was publish.

6- The system redirects the admin to the admin page.

Alternative flow: Invalid Data

1- The system presents a message to inform the admin that exist fields that were filled in a incorrect way

2- The admin corrects the fields

3- The flux continues in the step 3 of the main flow.

Post-condition: Post registered in the system.

Answer 1

TL;DR

Every organization has its own way of defining requirements. There is no "one true way" to specify them. If you want to know how requirements should be written in your organization, you'll need to ask someone who works there.

Generically, though, you can pull out the behaviors of the system and specify what the system is supposed to do, and who the consumer of that behavior is. The specific details of how the system does these things—in other words, how the engineers implement the underlying behavior—is quite often irrelevant to the specification because functional requirements are about behaviors and outcomes.

Once you've identified the essential behaviors, you can write your specifications any way you like. Two common ways are declarative specifications and executable specifications.

Focus on "What," Not "How"

Functional requirements describe behaviors of a system, while non-functional requirements are about its properties. To find the functional requirements, you generally want to focus on something the system does rather than on how it does it.

Your Examples

In your examples, you're too focused on how the functionality is implemented. If that's required in your organization, then do that. Otherwise, specify how the system behaves rather than how the specification is implemented.

Identifying Functions

First, who is the consumer of the behavior? In your examples, it's the administrator.

Next, identify what the behaviors or outcomes are for the administrator given a specific trigger or input to the function. In your example, some obvious behaviors are: authentication, validation, and redirection.

1. The system SHALL require an administrator to be authenticated prior to creating an event.
2. The system SHALL validate the administrator's event before publishing it.
3. The system SHALL NOT store invalid events.
4. The system SHALL display errors for invalid events.
5. The system SHALL redirect to the event form when event data is invalid.
6. The system SHALL redirect to the admin page when event data is published.

That's pretty much it at the functional level. You'll note that #3 is crossed out. That's because I would argue that #3 is a non-functional requirement that describes a property of the system rather than a behavior, but I think it could be argued either way.

Tip: However you choose to draw the distinction between functional and non-functional requirements, just be consistent about it!

Executable Specifications

Rather than writing specifications for each procedural step, or function, another approach is to declare what the system must do (or not do) when a given behavior is triggered. In your example, the consumer is the administrator. If you express it using Cucumber's Gherkin syntax, key elements of your use case look more like this:

Scenario: successfully publish a valid event
    GIVEN that the administrator is logged in,
    WHEN the administrator publishes a valid event
    THEN the system stores the event in the database
    AND THEN displays the admin page.

Scenario: fail to publish an invalid event
    GIVEN that the administrator is logged in,
    WHEN the administrator publishes an invalid event
    THEN the system displays an error message
    AND THEN presents the event screen for corrections.

A long list of shall or shall-not statements is very hard to reason about, and very hard to test. I find this form of functional behavior a lot more readable than declarative specifications because it reads almost like natural language. Furthermore, this sort of planning is inherently more testable. Wouldn't it be better to have a set of requirements where the implementation can be validated automatically instead of by hand?

Behavior Driven Development (BDD) and Acceptance Test Driven Development (ATDD) do require thinking a little differently about how you write your specifications, but it's usually worth the extra effort. However, your organizational values may vary.

Answer 2

There are certain aspects about requirements which will always be discussed controversially.

As an example, some organisations prefer conditions to be mentioned at the end of requirements, not at the beginning. This may sound irritating at first, but it does have an advantage: Conditions may occasionally be a bit lengthy, and in such cases, it is nice to be able and keep the functionality in mind while working one's way through the preconditions.

Apart from that, it's true that some things don't matter -- unless you have to maintain requirements, in which case some styles are more handy than others.

I consider the following prerequisites as a must:

• An explicitly well-defined and consistently applied "must" / "should" / "may" nomenclature / convention
• A well-defined and consistently used glossary

Getting closer to your question, I strongly recommend watching passive and active wording in conjunction with the true actor. Yes, in a use case, the administrator is the actor. But yes, the system processes the actor's input.

Consider the following requirement: The user must be able to sort the list. This is clearly a requirement about the ability of the user to sort a certain list. It could indirectly mean that the system must provide a kind of the list which the user can then sort, e.g. by printing it, cutting it into pieces, and rearranging it on the wall with glue -- based on the user's knowledge which is explicitly required here.

Ragarding your examples:

When a user submit his credentials and they are valid, the system shall initiate the session of this user

Weak points: "they are valid" (passive), where does the user submit the credentials to, how is a session defined, and why is the requirement limited to users submitting their own requirements when it is most likely that the system will be unable to identify that a user submits another user's credentials?

Counter proposal:

Terminology

In this document, the word "shall" denotes mandatory requireemnts, "should" denotes desirable requirements, and "may" denotes optional requirements.

Glossary

Credentials:  ... TBD
Login Screen: ... TBD
Session:      ... TBD
User:         ... TBD

Requirements

#1
While there is no active -> Session,
the system shall block access to all data and
instead present the -> Login Screen.

#2
When a -> User submits -> Credentials via the -> Login Screen,
the system shall initiate a -> Session for the respectice -> Credentials.

The admin shall be able to fill and submit the information relative to a post.

Weak points: "the admin shall be able" (passive), what is "the information relative" to a post?

When an admin fill and submits the post information, the system should store in the database that information.

Weak points: What is "post information", why suddenly "should" instead of "shall", why a database?

Counter proposal:

Glossary Extensions

Admin:  -> Role with unlimied -> Rights
Rights: -> Definition of allowance of specific operations operations
Role:   -> Information about -> Rights, associated to -> User

Additional Requirements

#3
If the -> Session -> User is an -> Admin,
the system shall display a form to edit post information
(see [Glossary / Reference / ...]).

#4
If the -> Session -> User is an -> Admin,
the system shall replace existing post information
(see [Glossary / Reference / ...]) persistently
by post information submitted as per #3.

These are just suggestions to demonstrate how mainainability, architecture and implementation details may or may not be addressed by requirements. Here, I omitted the "databse" easily because it was not necessary (and it's a good idea to omit unnecessary aspects). As opposed to that, I separated session management somewhat. Also, following a Model-View-Controller pattern will not be too difficult, because I introduced one requirement for the View (#3) and one for the Controller (#4). The interesting aspect here is that this explicitly requires a double check. You may or may not want to have this.

Also, depending on your organisation, my exact suggestions may not be liked by many. Still, all these aspects do play a role when writing requirements.