Generguide Requirements


This project aims to produce a Software Developer's Guide which can be used by many projects by providing generic sections and allowing users to easily modify sections to create their own Guide.

Requirements contain a or a indicating whether the requirement has been addressed in the design. The links to the section of the design which implements the requirement. The may link to discussion in the design about difficulties in implementing the requirement.

Key words to Indicate Requirement Levels

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.


Generic Guide

A source document or guide stored in the source format (probably simple Docbook).


A project which is to be documented.

Project Guide

A guide explaining processes used by the project.


Documentation Format

Table 4. Documentation Format

rdocformat1Documentation shall be stored in standards based format.High
rdocformat2Documentation should be stored in a format which can be transformed into other common formats. In particular: text, html, pdf.High
rdocformat3.1Documentation shall be editable with an easy to use, no cost, WYSIWYM editor.Medium
rdocformat3.2Documentation shall be editable with an easy to use, open source, WYSIWYM editor.Medium
rdocformat4The learning curve required to write documentation should be kept as short as possible in order to attract authors.Medium
rdocformat5The documentation format shall allow sections of a Generic Guide to be edited and stored separately to the Project Guide.High


Table 5. Sections

rsections1It shall be possible for one section to be incorporated into multiple Project Guides.High
rsections2It shall be possible for a Project Guide to use a subset of Generic Guide sections.High
rsections3It shall be possible for a user to replace a section from a Generic Guide.Medium
rsections4It shall be possible for a user add a section which is external Generic Guide. The added section can be added in into the Generic Guide wherever a section can be added.Medium
rsections5It shall be possible for a section to include project specific information. For instance, a generic section describing how to conduct meetings will reference project specific information about the meeting time.Medium
rsections6A Project Guide shall not contain unwanted sections from the Generic Guide.Low
rsections7It shall be possible to have different sets of generic sections. For instance, you could have on set of sections in English and another in French. Or one set which recommends tools from Open Source Software and another which recommends Commercial Software. Or a Installation Guide, Users Guide and Developers Guide which share some sections but not others.Medium


Generguide will provide a configuration file which specifies what content is to be incorporated in a Project Guide.

Table 6. Configuration


A user may specify a section in a configuration file, then the section author may spawn new subsections. The user will want to use the subsections without changing their configuration file.

The configuration shall allow a section to be included and all subsections not specifically excluded will be included as well.

This is a black list filter.

rconfig2A user may want a limited subset of subsections. The configuration file is to include only the specified sections even after the extra sections are added to the Generic Guide.

A configuration shall be able to specify only the subsections to include.

This is a white list filter.

rconfig3Hopefully, generguide will be used to describe processes from all sorts of industries. All industry processes could be stored on the generguide site, however this will force all industries to use the same development rules and will hinder development of fringe processes.

A configuration shall be able to reference sections from another namespace on the internet.

rconfig4In the configuration, it shall be possible to specify which version of a section to use. The version can be set to "head", "stable", or a version number. The version number shall be of the form: "x.x.x" where x is a number.High
rconfig5It is much easier to write a generic section if you can specify variable names which are filled out by the user of the section. For instance, "project_name", "project_URL", etc. Generguide sections shall be able to use variable names than can be edited in an external document by users of the section.High

Build Process

Table 7. Build Process

rbuildprocess1The documentation build process shall be able to be run by the maven build tool.Medium
rbuildprocess2The documentation build process shall be able to be run by the ant, a build tool.Medium
rbuildprocess3The documentation build process shall be able to be run by 'make', a build tool.Medium
rbuildprocess4The documentation build process shall produce a html guide based on input sections.High
rbuildprocess5Users shall be able to tailor a project specific guide using a GUI data entry form.Medium
rbuildprocess6The build process shall be able be able to be run on multiple platforms. In particular: windows, linux, mac.High

Configuration Management

Table 8. Configuration Management

rconfigurationmanagement1Multiple users shall be able to modify one section.Medium
rconfigurationmanagement2A guide shall be able to include stable sections while the head version is being updated.High
rconfigurationmanagement3Users shall be able to reference sections by version number. For example, a user may want to continue using an old coding standard to support an old project, but update building section to use the latest version.High
rconfigurationmanagement4Each section shall have a defined process defined for updating it. This process may be common for all sections.High
rconfigurationmanagement5Users impacted by an updated section shall be notified if they so desire.High

Documentation Contexts

Table 9. Documentation Contents

rdoccontents1Authors shall be credited if they so desire.Medium
rdoccontents2Documentation shall follow a standard format.Medium

Generguide's target market is open source developers who often don't have the money or the inclination to buy software.

Hence, tools that cost money shall not be recommended by the master generguide documentation.

Sections explaining cost-tools can be hosted on external sites and advertised by these sites.

Tools that provide a free license for open source projects will be considered if alternatives are not available.

rdoccontents4All things being equal, open source tools shall be recommended over no-cost tools.Low


Table 10. Scalable

rscalable1The generguide framework shall support up to 100 sections.High
rscalable2The generguide framework shall support up to 1000 sections.Medium
rscalable3The generguide framework shall support infinite sections.Low

Legacy Data

Many potential generguide users will not be able to use generguide unless they have a means to incorporate large amounts of legacy documentation into the generguide framework. This means either support standard formats or provide import utilities to import formats into the generguide supported formats.

Table 11. Legacy Data

legacy1Simple Docbook documents shall be able to be imported into the generguide framework.Medium
legacy2Docbook XML documents shall be able to be imported into the generguide framework.Medium
legacy3Docbook non-XML documents shall be able to be imported into the generguide framework.Medium
legacy4Microsoft Word documents shall be able to be imported into the generguide framework.Medium


Source generguide documentation may be located at numerous locations on the web. This means generguide tools will be faced with logistical problems related to the reliability, speed and bandwidth cost of the web.

Table 12. Bandwidth

rcaching1If all generconfig source documentation resides on the local computer, then generconfig tools shall be able to be executed without connecting to the web.Low
rcaching2Generconfig tools will be able to cache external source documentation when executing. Subsequent execution of the tool shall be able to execute and produce the same results without being connected to the web.Low