5

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 create my own increasingly complex programs, apps and sites the more I feel the need for a good requirement document. Since most of what I work on is my own work, I need to write those requirements.

What is the process for a software requirement documentation. I imagine it will describe what the product should provide to the end-user along with any perfermance/memory constraints. I also assume that it will have other constraints, such as where the data will be provided from. And it is probably independent of solutions. That comes later.

So am I on the mark, or missing anything? What do these documents look like?

  • I'm voting to close this question as off-topic because it can be better answered on the software engineering stack. Their on-topic section specifically includes questions about requirements. – linksassin Mar 14 at 3:59
  • 5
    @linksassin Being on topic on another site is explicitly not a valid close reason. It is still on-topic here and this is the site I chose to ask on. – bruglesco Mar 14 at 4:00
  • 1
    From personal knowledge I believe this is too technical for this site. This isn't about the art of literary works but documents structure and requirements engineering. Perhaps I should have explained better. If you want help with how to improve the writing of your requirements that would be on-topic. As written this reads more like "how to write requirements" which is a technical task that encompasses a lot more than just writing. – linksassin Mar 14 at 4:04
  • 7
    @linksassin I came to this community because it was actively encouraging activity in the technical-writing tag. This community is not meant to be solely for creative-writing alone. Many of the people here are technical writers and it's them that I want answers from. I have not been disappointed in the past answers Ive gotten in this tag. – bruglesco Mar 14 at 4:12
  • 1
    I've recently read a nice article on documenting requirements: Engineering guide to writing correct User Stories. It covers both tools choice and the overall guidelines on writing requirements that are full, exact and non-ambiguant. – Nick Volynkin Mar 15 at 4:31
4

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:

  1. Describe the context of the project, supplemented with a case study
  2. Identify stakeholders (users, domain experts, management, standards, customers, systems engineers and maintainers, marketing and sales, etc.) and then collect and develop requirements.
  3. Model the proposed system, identify system actors (external forces) and information flow in and out of the system (as well as interaction points)
  4. 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

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.