requirements-template.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="requirements-template" xreflabel="Requirements Template">
<title>System/Application Requirements Template</title>
<authorblurb>
<para>By <ulink url="mailto:youremail@example.com">You</ulink></para>
</authorblurb>
<sect2 id="yourpackage-requirements-introduction">
<title>Introduction</title>
<para>
<emphasis>Briefly explain to the reader what this document is for, whether
it records the requirements for a new system, a client application, a
toolkit subsystem, etc. Remember your audience: fellow programmers,
AND interested non-technical parties such as potential clients, who
may all want to see how rigorous our engineering process is. Here and
everywhere, write clearly and precisely; for requirements
documentation, write at a level that any intelligent layperson can
understand.</emphasis>
</para>
</sect2>
<sect2 id="yourpackage-requirements-vision">
<title>Vision Statement</title>
<para>
<emphasis>Very broadly, describe how the system meets a need of a business,
group, the OpenACS as a whole, etc. Make sure that technical and
non-technical readers alike would understand what the system would do
and why it's useful. Whenever applicable, you should explicitly state
what the business value of the system is. </emphasis>
</para>
</sect2>
<sect2 id="yourpackage-requirements-system-app-overview">
<title>System/Application Overview</title>
<para>
<emphasis>Discuss the high-level breakdown of the components that make up
the system. You can go by functional areas, by the main transactions
the system allows, etc. </emphasis>
</para>
<para>
<emphasis>You should also state the context and dependencies of the system
here, e.g. if it's an application-level package for OpenACS 4, briefly
describe how it uses kernel services, like permissions or subsites. </emphasis>
</para>
</sect2>
<sect2 id="yourpackage-requirements-cases">
<title>Use-cases and User-scenarios</title>
<para>
<emphasis>Determine the types or classes of users who would use the
system, and what their experience would be like at a high-level.
Sketch what their experience would be like and what actions they would
take, and how the system would support them.</emphasis>
</para>
</sect2>
<sect2 id="yourpackage-requirements-competitive-analysis">
<title>Optional: Competitive Analysis</title>
<para>
<emphasis>Describe other systems or services that are comparable to what
you're building. If applicable, say why your implementation will be
superior, where it will match the competition, and where/why it will
lack existing best-of-breed capabilities. This section is also in the
Design doc, so write about it where you deem most appropriate.</emphasis>
</para>
</sect2>
<sect2 id="yourpackage-requirements-links">
<title>Related Links</title>
<para>Include all pertinent links to supporting and related material,
such as: </para>
<itemizedlist>
<listitem><para> System/Package "coversheet" - where all documentation for this software is linked off of</para></listitem>
<listitem><para> Design document</para></listitem>
<listitem><para> Developer's guide</para></listitem>
<listitem><para> User's guide</para></listitem>
<listitem><para> Other-cool-system-related-to-this-one document</para></listitem>
<listitem><para> Test plan </para></listitem>
<listitem><para> Competitive system(s)</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="yourpackage-requirements-requirements">
<title>Requirements</title>
<para>
<emphasis>The main course of the document, requirements. Break up the
requirements sections (A, B, C, etc.) as needed. Within each section,
create a list denominated with unique identifiers that reflect any
functional hierarchy present, e.g. 20.5.13. - for the first number,
leave generous gaps on the first writing of requirements (e.g. 1, 10,
20, 30, 40, etc.) because you'll want to leave room for any missing
key requirements that may arise. </emphasis>
</para>
<itemizedlist>
<listitem>
<para><emphasis role="strong">10.0 A Common Solution</emphasis></para>
<para>
Programmers and designers should only have to learn a single
system that serves as a UI substrate for all the functionally
specific modules in the toolkit.
</para>
<blockquote>
<para><emphasis role="strong">10.0.1</emphasis></para>
<para>
The system should not make any assumptions about how pages should
look or function.
</para>
<para><emphasis role="strong">10.0.5</emphasis></para>
<para>
Publishers should be able to change the default presentation of
any module using a single methodology with minimal exposure to
code.
</para>
</blockquote>
</listitem>
</itemizedlist>
<para>
For guidelines writing requirements, take a look at <ulink url="http://www.utm.mx/~caff/doc/OpenUPWeb/openup/guidances/guidelines/writing_good_requirements_48248536.html">
quality standards</ulink> or <ulink
url="https://ep.jhu.edu/about-us/news-and-media/writing-good-requirements-checklists">requirements
checklist</ulink>, along with a good example, such as <xref linkend="apm-requirements"/>.
</para>
<para>
Besides writing requirements in natural language, consider using the
following techniques as needed:
</para>
<itemizedlist>
<listitem><para> Pseudocode - a quasi programming language, combining the
informality of natural language with the strict syntax and control
structures of a programming language. </para></listitem>
<listitem><para> Finite State Machines - a hypothetical machine that can be in
only one of a given number of states at any specific time. Useful to
model situations that are rigidly deterministic, that is, any set of
inputs mathematically determines the system outputs. </para></listitem>
<listitem><para> Decision Trees and Decision Tables - similar to FSMs, but better
suited to handle combinations of inputs. </para></listitem>
<listitem><para> Flowcharts - easy to draw and understand, suited for event and
decision driven systems. UML is the industry standard here.</para></listitem>
<listitem><para> Entity-Relationship diagrams - a necessary part of Design
documents, sometimes a high-level ER diagram is useful for
requirements as well.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="yourpackage-requirements-implementation">
<title>Optional: Implementation Notes</title>
<para>
<emphasis>Although in theory coding comes after design, which comes after
requirements, we do not, and perhaps should not, always follow such a
rigid process (aka the waterfall lifecycle). Often, there is a
pre-existing system or prototype first, and thus you may want to write
some thoughts on implementation, for aiding and guiding yourself or
other programmers. </emphasis>
</para>
</sect2>
<sect2 id="yourpackage-revision-history">
<title>Revision History</title>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry role="revisionheader">Document Revision #</entry>
<entry>Action Taken, Notes</entry>
<entry>When?</entry>
<entry>By Whom?</entry>
</row>
</thead>
<tbody>
<row>
<entry role="revisionbody">0.3</entry>
<entry>Edited further, incorporated feedback from Michael Yoon</entry>
<entry>9/05/2000</entry>
<entry>Kai Wu</entry>
</row>
<row>
<entry>0.2</entry>
<entry>Edited</entry>
<entry>8/22/2000</entry>
<entry>Kai Wu</entry>
</row>
<row>
<entry>0.1</entry>
<entry>Created</entry>
<entry>8/21/2000</entry>
<entry>Josh Finkler, Audrey McLoghlin</entry>
</row>
</tbody></tgroup></informaltable>
<para><phrase role="cvstag">($Id: requirements-template.xml,v 1.7.2.2 2020/07/02 08:39:25 gustafn Exp $)</phrase></para>
</sect2>
</sect1>
