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.
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.
A source document or guide stored in the source format (probably simple Docbook).
A project which is to be documented.
A guide explaining processes used by the project.
Table 4. Documentation Format
|rdocformat1||Documentation shall be stored in standards based format.||High|
|rdocformat2||Documentation should be stored in a format which can be transformed into other common formats. In particular: text, html, pdf.||High|
|rdocformat3.1||Documentation shall be editable with an easy to use, no cost, WYSIWYM editor.||Medium|
|rdocformat3.2||Documentation shall be editable with an easy to use, open source, WYSIWYM editor.||Medium|
|rdocformat4||The learning curve required to write documentation should be kept as short as possible in order to attract authors.||Medium|
|rdocformat5||The documentation format shall allow sections of a Generic Guide to be edited and stored separately to the Project Guide.||High|
Table 5. Sections
|rsections1||It shall be possible for one section to be incorporated into multiple Project Guides.||High|
|rsections2||It shall be possible for a Project Guide to use a subset of Generic Guide sections.||High|
|rsections3||It shall be possible for a user to replace a section from a Generic Guide.||Medium|
|rsections4||It 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|
|rsections5||It 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|
|rsections6||A Project Guide shall not contain unwanted sections from the Generic Guide.||Low|
|rsections7||It 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.
|rconfig2||A 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.
|rconfig3||Hopefully, 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.
|rconfig4||In 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|
|rconfig5||It 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|
Table 7. Build Process
|rbuildprocess1||The documentation build process shall be able to be run by the maven build tool.||Medium|
|rbuildprocess2||The documentation build process shall be able to be run by the ant, a build tool.||Medium|
|rbuildprocess3||The documentation build process shall be able to be run by 'make', a build tool.||Medium|
|rbuildprocess4||The documentation build process shall produce a html guide based on input sections.||High|
|rbuildprocess5||Users shall be able to tailor a project specific guide using a GUI data entry form.||Medium|
|rbuildprocess6||The build process shall be able be able to be run on multiple platforms. In particular: windows, linux, mac.||High|
Table 8. Configuration Management
|rconfigurationmanagement1||Multiple users shall be able to modify one section.||Medium|
|rconfigurationmanagement2||A guide shall be able to include stable sections while the head version is being updated.||High|
|rconfigurationmanagement3||Users 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|
|rconfigurationmanagement4||Each section shall have a defined process defined for updating it. This process may be common for all sections.||High|
|rconfigurationmanagement5||Users impacted by an updated section shall be notified if they so desire.||High|
Table 9. Documentation Contents
|rdoccontents1||Authors shall be credited if they so desire.||Medium|
|rdoccontents2||Documentation 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.
|rdoccontents4||All things being equal, open source tools shall be recommended over no-cost tools.||Low|
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
|legacy1||Simple Docbook documents shall be able to be imported into the generguide framework.||Medium|
|legacy2||Docbook XML documents shall be able to be imported into the generguide framework.||Medium|
|legacy3||Docbook non-XML documents shall be able to be imported into the generguide framework.||Medium|
|legacy4||Microsoft 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
|rcaching1||If all generconfig source documentation resides on the local computer, then generconfig tools shall be able to be executed without connecting to the web.||Low|
|rcaching2||Generconfig 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|