: Documenting software requirements As a self-taught developer the only requirement documents I've ever been privileged to read are those of hackerrank and the sort. However the more and more I

Vote Up Vote Down

Requirements can be broadly categorised as follows (using FURPS):

Functionality: functional requirements (see also this stack overflow question)
Usability: Human factors, aesthetics and style, consistency, documentation
Reliability: reliability requirements
Performance: quantifiable requirements such as response time
Supportability: requirements to ensure it is testable, configurable, able to be installed and serviced

If you are attempting to develop formal requirements, try ISO/IEC/IEEE 29148:2018 Systems and software engineering -- Life cycle processes - Requirements engineering.

For large systems, you could also look at approaches such as SYSMOD that you can use to model the requirements and the system architecture. Using this approach, you would:

Describe the context of the project, supplemented with a case study
Identify stakeholders (users, domain experts, management, standards, customers, systems engineers and maintainers, marketing and sales, etc.) and then collect and develop requirements.
Model the proposed system, identify system actors (external forces) and information flow in and out of the system (as well as interaction points)
Identify use cases (stories) that involve the actors from the previous steps. Model these interactions, derive system interfaces, look at internal structures, etc.

For your average project, you will likely want to do something in-between. An important aspect of requirements engineering that should be mentioned is the back-and-forth between the engineering team and the stakeholders. Requirements are used by developers, testers, business analysts, technical writers, marketing and sales, and the customer as a method of communication. It describes the system that you are building - a shared vision. It can take many iterations for requirements to be agreed upon and without that communication it wont matter what you write!

(0)

Vote Up Vote Down

There are almost as many ways to document software as there are to program it, and the important thing to remember is to keep focus on what you are actually trying to achieve with it: To provide aid and support to the development and use of software.

Typically the goal is to develop two key documents:
1. A functional specification, describing what is to be done.
2. A technical specification, describing how something is to be achieved.

Both of these documents should at all times attempt to answer why decisions are made. [The details of why something should be done one way, or why something was important is frequently overlooked in software development. While the answer may appear painfully obvious at the time the decision is made, it frequently not documented, and readily forgotten. This risks eventually developing some very nasty little bugs down the road, or difficulty in tracking down issues.]

Without details on the nature of the system being designed, it is difficult to provide specific details on what these documents should look like or firm guidelines on how to write them.

A general starting point however is to layout the core 'minimum viable system', strip back every last thing you can from the software you're thinking of to the very core purpose of what you are attempting. From that point you can begin revisions as you expand the functional specs, from which you can build out the technical specs.

Whether you break these documents down on functions, screens, widgets, or some other manner will depend on what the software is doing, and how it works.
- A screen focused documentation style is unlikely to serve a project to build an environmental logging system that packages data to be sent out over the network.

(0)