Specification docs for various development teams and other stakeholders. Hopefully for fdik->core_dump :)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 

5.9 KiB

Specification Template

Front matter

  • Title
  • Author(s)
  • Team
  • Reviewer(s)
  • Created
  • Last updated
  • Ticket reference link (where applicable)

Introduction

This is a rough template for something like a technical specification. There are so many different levels this can be done at that I wanted to give a framework with emphasis on the parts that we don't do well, that are poorly understood, and that are challenging. There is room for all of the rest, and this is only a template.

You will note that there is less specific emphasis on exactly how solutions should be laid out when the technical area arrives, because that is highly dependent on the problem and solution. One of the most serious drawbacks of government-style requirements engineering specifications is that the format tends to overwhelm form and get in the way of communicating the actual information.

At the same time, our current ad-hoc process is completely insufficient - "here are some states we have or some message types that will be sent" is so low-information that it is unactionable.

Having done systems engineering level formal specifications for government contractors, I want to avoid the process-for-the-sake-of-process rigidity of those specifications (because they are time consuming and often impede results) and recognise the limited nature of our resources to make the best use of them.

This is a tool. Extended discussions about formal requirements language are out-of-scope here; if you plan to write a spec, you do what you need to do. This reflects a superset of what I, as a team lead and developer, would expect to see and be able to work with.

Overview, Problem Description, Summary, or Abstract

Motivation for what you are proposing. If you feed the specification consumer a plan and they don't know why you're doing it, it's not really a plan for anything.

We're all technical, and tend to think the technical parts showing the bits and pieces of our solution are the most important thing, but this section is actually the cornerstone of your document, and it will be the hardest to write.

It is not sufficient, but it is absolutely necessary.

This section should contain at least the following:

  1. Context for the problem what you are specifying will solve. You must situate what you are proposing.

  2. Summary of the problem.

    • Try to view this from highest stakeholder viewpoint this impacts. If it is a user problem, explain the user problem. If it causes issues for application developers without impacting actual users, explain it from this view. If its impacts are only engine-internal, then give the summary from this viewpoint. You have ample opportunity to clarify low-level impacts deeper within the document
  3. Suggested solution

    • This is where you give a high-level explanation. No state machines, no protocols. This is a description - a placeholder for later details,
  4. The stakeholders

    • Define those involved in the problem and the solution, and make sure you clarify for whom this document is intended

Glossary

Background

This should contain information such as the origin of the problem and why it is worth solving, who the problem impacts, how it impacts them, and how the problem interacts with and impacts other parts of the system.

Goals or Product and Technical Requirements

  • Overall requirements driven by user examples - these can be used again and drawn through the document as illustration if need be
  • Technical requirements

Non-Goals or Out of Scope

Future Goals

Assumptions

  • Conditions and resources that need to be present and accessible for the solution to work as described.

Proposed solution

Status quo

Discussion of how this problem may currently be being handled, or, if it is not, why the current system cannot handle it, and the pros and cons of leaving things as they are now

Proposed Solution / Design

Overview of solution

This is very high level. What, if you had five minutes to explain the solution to someone who does not know all the details of the system, would you say to someone to give them an idea of what the solution does or involves. Presume an ill-informed audience who is not going to pay attention to the details YOU care about - that comes later.

External components that the solution will interact with and that it will alter

This is important to be able to frame who needs the document as well as guiding you, as the writer, to the perspectives you need to present in the solution

Dependencies

Pros and cons of the proposed solution

Solution logic and protocols

This needs to be described in terms of each part of the system it impacts.

This should include the following, where applicable, and in an order that makes sense:

  • API information and changes
  • DDL information and changes
  • Protocol descriptions, including examples
  • Pseudocode, state machines, flowcharts
  • Error and failure states, and how those should be handled internally and externally
  • Limitations and caveats

Service requirements

This should make it clear what needs to be incorporated into the solution so that service can give appropriate feedback. This includes tools, logging, and other infrastructure that may need to be developed or modified.

Deployment and release plan

  • Notification to other teams who may need to modify systems
  • Coordination of how impacted systems will deploy or release in concert with solution
  • Plan for communicating changes, warnings, caveats for new behaviour to affected stakeholders

Impacts and follow-on requirements

  • Which teams will be impacted by this solution, and how can that impact be measured and minimised?
  • What impacts does this solution have on stakeholders? What will it require of them?
  • What requirements does this solution generate now and in the future?

Alternatives, Risks

Security and privacy considerations

Known issues, with possible solutions and mitigation

Open questions