<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'>
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>System/Application Requirements Template</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="filename.html" title="Detailed Design Documentation Template"><link rel="next" href="i18n.html" title="Chapter 14. Internationalization"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="requirements-template"></a>System/Application Requirements Template</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:youremail@example.com" target="_top">You</a></p>
          OpenACS docs are written by the named authors, and may be edited
          by OpenACS documentation staff.
        </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div></div><p>
      <span class="emphasis"><em>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.</em></span> 
    </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div></div><p>


      <span class="emphasis"><em>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. </em></span>
    </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div></div><p>
      <span class="emphasis"><em>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. </em></span> 
    </p><p>
      <span class="emphasis"><em>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. </em></span>
    </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div></div><p>
      <span class="emphasis"><em>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.</em></span>  
    </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div></div><p>
      <span class="emphasis"><em>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.</em></span>
    </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-links"></a>Related Links</h3></div></div></div><p>Include all pertinent links to supporting and related material,
      such as: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li><li class="listitem"><p> Design document</p></li><li class="listitem"><p> Developer's guide</p></li><li class="listitem"><p> User's guide</p></li><li class="listitem"><p> Other-cool-system-related-to-this-one document</p></li><li class="listitem"><p> Test plan </p></li><li class="listitem"><p> Competitive system(s)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div></div><p>
      <span class="emphasis"><em>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.  </em></span>
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>10.0 A Common Solution</strong></span></p><p>
	  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. 
	</p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>10.0.1</strong></span></p><p>
	    The system should not make any assumptions about how pages should
	    look or function.
	  </p><p><span class="strong"><strong>10.0.5</strong></span></p><p>
	    Publishers should be able to change the default presentation of
	    any module using a single methodology with minimal exposure to
	    code.
	  </p></blockquote></div></li></ul></div><p>
      For guidelines writing requirements, take a look at <a class="ulink" href="http://www.utm.mx/~caff/doc/OpenUPWeb/openup/guidances/guidelines/writing_good_requirements_48248536.html" target="_top">
	quality standards</a> or <a class="ulink" href="https://ep.jhu.edu/about-us/news-and-media/writing-good-requirements-checklists" target="_top">requirements
	checklist</a>, along with a good example, such as <a class="xref" href="apm-requirements.html" title="Package Manager Requirements">Package Manager Requirements</a>.
    </p><p>
      Besides writing requirements in natural language, consider using the
      following techniques as needed:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Pseudocode - a quasi programming language, combining the
	  informality of natural language with the strict syntax and control
	  structures of a programming language. </p></li><li class="listitem"><p> 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. </p></li><li class="listitem"><p> Decision Trees and Decision Tables - similar to FSMs, but better
	  suited to handle combinations of inputs.  </p></li><li class="listitem"><p> Flowcharts - easy to draw and understand, suited for event and
	  decision driven systems.  UML is the industry standard here.</p></li><li class="listitem"><p> Entity-Relationship diagrams - a necessary part of Design
	  documents, sometimes a high-level ER diagram is useful for
	  requirements as well.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div></div><p>
      <span class="emphasis"><em>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. </em></span> 
    </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-revision-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th class="revisionheader">Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td class="revisionbody">0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><div class="cvstag">($Id: requirements-template.html,v 1.54 2024/09/11 06:15:47 gustafn Exp $)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr><tr><td width="40%" align="left">Detailed Design Documentation Template </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Chapter 14. Internationalization</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html>