How to document non-functional requirements (NFRs) in a story/feature?

Question 1

Q1: Yes, definitely they can. Take a look on that article describing Handling Non Functional Requirements in User Stories.

Q2. From my perspective if you able to create them it's really worth of keeping and tracking them in such a way. But citing this article

There is no magical agile practice that helps you uncover NFR. The first step is to take responsibility. NFR can be represented as User Stories if the team finds a that this helps to keep these visible. However, be aware that surfacing such stories may create issues around the priority of work done on them against more obvious features.

Q3. Take a look on the mentioned article from Q1.

Question 2

I'll give an answer by working through an example.

Let us say that your team has already implemented the following story:

Scenario: User can log in to the website
   Given I have entered my login credentials
   When I submit these credentials
   Then I get navigated to my home screen

To answer Question 1) - Can the non-functional requirement be specified as a story?

The project stakeholders have given you a NFR which reads:

For all website actions, a user should wait no longer that five seconds for a response.

You could create a story for this as follows:

Scenario: User can log in to the website in a timely fashion
   Given I have entered my login credentials
   When I submit these credentials
   Then I get navigated to my home screen
   And I should have to wait no longer than the maximum acceptable wait time

Note that instead of imperatively specifying '5' seconds, I have kept the scenario declarative and instead specified "wait no longer than the maximum acceptable wait time".

To answer question 2) - Should the non-functional requirement be specified as a story?

The NFRs should definitely be specified as a story.

Creating a story will allow this task's complexity to be estimated (so that the team can determine how difficult it is relative to past stories), plus the team can break the story down into tasks (which can be estimated in hours, so that you can work out if the team can implement this story in the current sprint).

Hence in my contrived example, the team would have already implemented the code to log-in, but they'd then determine how to implement the requirement that it must take no longer than 5 seconds to log in. You will also allow be able to explore the inverse of this problem i.e. what happens if it takes longer than five seconds to log-in? e.g.

Scenario: User encounters a delay when logging in to the website
       Given I have entered my login credentials
       When I submit these credentials
       And I wait for over the the maximum acceptable wait time
       Then the Production team is informed
       And the problem is logged
       And I get navigated to my home screen

And finally, regarding question 3) - What would the story look like?

I've detailed how the stories would look like in answers 1) and 2)

Question 3

I think the boundaries of NFRs are still not fully agreed upon by everyone. Consider a story that says "As a manager, my employee must get all responses within 5 seconds to avoid hiring a second data entry person and adding $50,000 in payroll expenses." I consider that a fully functional business requirement, along with any performance requirements that focus on the end user experience.

I categorize "traditional" NFRs as stories where the impacted person is not in the end user's or stakeholder's organization. "As a support person I need logs of the web site traffic to help me troubleshoot problems," or "As a software maintainer, I need a block architecture diagram to help me make changes." Including the role as you would with any user story helps with prioritization. It also helps identify the stakeholder for that NFR, should you have any questions about it.

NFRs may include some aspects of performance, at least those that don't impact the end user. "As a system administrator, I want to allocate no more than 10GB of disk space to the database in order to use SQL Express and avoid expensive SQL Server licenses."

Consider a typical NFR that might only state "Databases are limited to 10GB." It's an arbitrary number with no meaning or rationale, and there's no way to question it. Having the story-like role and explanation helps everyone understand that there is a valid reason for the NFR, so when you're prioritizing them you can ask smart questions. They lead to conversations like "I need to expand my table space to 20GB, but the sysadmin has this NFR about database size. How much do SQL Server licenses really cost him? OMG, that much? OK, I'll denormalize a few tables and save a few GB to fit it in there."

Question 4

As both @bensmith and @siemic show, yes, you can can capture NFRs as stories.

Should you capture them in this way?

I don't think you want to capture NFRs as part of regular feature stories.

Most NFRs apply to more than one story. "The system must be responsive" means every story needs to define maximum wait times. "The system must not consume more than 10GB of disk space" means every story needs to consider disk space. The list of "and"s in the story becomes unmanageable in even trivial cases.

You may want to capture NFRs as independent stories, if both the product owner and team are comfortable with this.

For instance:

Given I have a PC with at least a dual core processor 
  and 8GB of RAM
  and a gigabit connection to the system
when I interact with the system
then I never have to wait more than 5 seconds for a response
 and 90% of attempts respond within 1 second

This provides a clear requirement, with measurable targets. You just have to make sure that each story takes all of the NFRs into account.

Question 5

I think you need to look at a few things, NFRs should follow the life span of the application, software, product etc. backup and recovery scenarios should be covered regularly, security scans and performance should be measured in prod as well as in development. Many NFRs need validation from teams outside of the development group so would not be expected to have a script or code written to verify. So obviously security, performance, scalability, resilience etc can and should be tested within the development phase or before code gets promoted into live. Most NFRs can be written up as stories but as said I dont think all need development effort to cover them. regards Martin