Technical Documentation StandardsV1.3

8/13/2019 Technical Documentation StandardsV1.3

1/30

TECHNICAL DOCUMENTATIONSTANDARD V1.3

Last change: AB 19/02/2010 07:49:00 1

Guidelines

Technical Documentation Standard forSoftware development

Author: Andreas BergerDate: 19.02.2010Version: 1.3


2/30


Last change: AB 19/02/2010 07:49:00 2

VERSIONING

V 0.1 First draft AB 08. November 2006

V 0.11 Various changes (Checklists,) AB 09. November 2006

V 1.0 Small changes done in the texts MB 10. November 2006

V 1.1 Added chapter Why documentation AB 12. November 2006

V 1.11 Fixed Typos and added references AB 14. November 2006

V 1.2 Added chapter Optional documentation AB 14. November 2006

V 1.3 Adjusted based on new requirements acc. tothe actual workflow

AB 19. February 2010


3/30


Last change: AB 19/02/2010 07:49:00 3

TABLE OF CONTENTS

VERSIONING .................................................................................................................. 21. PURPOSE OF THIS DOCUMENT ........................................................................ 51.1 Why does Specific-Group do documentation? ........................................................................... 6

1.1.1 Documentation helps at software development: ....................................................................... 61.1.2 Documentation keeps software-quality at high levels: .............................................................. 61.1.3 Documentation makes it easy to transfer projects: ............................ ....................................... 6

1.2 Why does Specific-Group notdocument everything? ................................................................ 71.2.1 Post-Documentation seldom makes sense: ............................................................................. 71.2.2 Documentation sometimes is academic: .................................................................................. 71.2.3 Documentation methods not always make sense: ................................................................... 7

1.3 Optional documentation ................................................................................................................ 82. METHODS ............................................................................................................. 92.1 Entity-Relationship Diagrams ...................................................................................................... 10

2.1.1 Description: ............................................................................................................................. 102.1.2 Usage: ..................................................................................................................................... 102.1.3 Main Components and Examples: .......................................................................................... 102.1.4 Checklist for SPG: .................................................................................................................. 112.1.5 Further Information: ................................................................................................................ 12

2.2 Table descriptions ........................................................................................................................ 132.2.1 Description: ............................................................................................................................. 132.2.2 Usage: ..................................................................................................................................... 132.2.3 Main Components and Examples: .......................................................................................... 132.2.4 Checklist for SPG: .................................................................................................................. 142.2.5

Further Information: ................................................................................................................ 14

2.3 Class diagram ............................................................................................................................... 15

2.3.1 Description: ............................................................................................................................. 152.3.2 Usage: ..................................................................................................................................... 152.3.3 Main Components and Examples: .......................................................................................... 152.3.4 Checklist for SPG: .................................................................................................................. 192.3.5 Further Information: ................................................................................................................ 19

2.4 Package diagram (class packages) ............................................................................................ 202.4.1 Description: ............................................................................................................................. 202.4.2 Usage: ..................................................................................................................................... 202.4.3 Main Components and Examples: .......................................................................................... 202.4.4 Checklist for SPG: .................................................................................................................. 202.4.5 Further Information: ................................................................................................................ 20

2.5 Sequence diagram ........................................................................................................................ 212.5.1 Description: ............................................................................................................................. 212.5.2 Usage: ..................................................................................................................................... 212.5.3 Main Components and Examples: .......................................................................................... 212.5.4 Checklist for SPG: .................................................................................................................. 212.5.5 Further Information: ................................................................................................................ 22

2.6 Dataflow Diagram ......................................................................................................................... 222.6.1 Description: ............................................................................................................................. 222.6.2 Usage: ..................................................................................................................................... 222.6.3 Main Components and Examples: .......................................................................................... 22


4/30


Last change: AB 19/02/2010 07:49:00 4

2.6.4 Checklist for SPG: .................................................................................................................. 222.6.5 Further Information: ................................................................................................................ 23

2.7 Workflow Diagram ........................................................................................................................ 232.7.1 Description: ............................................................................................................................. 232.7.2 Usage: ..................................................................................................................................... 232.7.3 Main Components and Examples: .......................................................................................... 242.7.4 Checklist for SPG: .................................................................................................................. 242.7.5 Further Information: ................................................................................................................ 24

2.8 Source code Commenting ........................................................................................................... 252.8.1 Description: ............................................................................................................................. 252.8.2 Usage: ..................................................................................................................................... 252.8.3 Main Components and Examples: .......................................................................................... 252.8.4 Checklist for SPG: .................................................................................................................. 272.8.5 Further Information: ................................................................................................................ 27

3. TECHNICAL DOCUMENTATION USAGE .......................................................... 283.1 Time Guide .................................................................................................................................... 293.2 Reasonability Guide ..................................................................................................................... 30


5/30


Last change: AB 19/02/2010 07:49:00 5

1. PURPOSE OF THIS DOCUMENT

This document shall provide a useful approach to software documentation, where bestdocumentation-practises of modern software-developer-companies are taken. Thismeans it shall avoid over-documentation that is expensive (since you need additionaltime for documentation-tasks which will reflect in the project-expenses). Generally it ispossible to document nearly everything in a large scale of available notifications andnorms. Usually only the most common ones are needed though, because plenty are ofvery little use (since redundant) and even most programmers and project-managerscant read or understand them.

Nonetheless it must be possible for professional developers, who are unfamiliar with theproject and the source code, to understand the software within a very short time, whichmeans a certain amount of documentation definitely must exist.

This document therefore offers a general approach for technical project-documentationthat orientates at profitableness and usefulness of certain documentation norms. Itexcludes documentation that is usually within the business-specifications (like use-cases,). It also does not explain all components of a diagram. Anyhow further links areusually provided.


6/30


Last change: AB 19/02/2010 07:49:00 6

1.1 Why does Specific-Group do documentation?There are various reasons for having documentation:

1.1.1 Documentation helps at software development:The key value of documentation is during the design process of new software, since ithelps the developer to see upcoming problems / problem solutions / preferable ways todo something / unclear specifications more clear. Usually documentation is anyhownothing but fixing the design-thoughts of a developer to paper, since while the creationprocess of software good coders tend to draw first drafts in some way. The only thingleft to do is standardization. Later on this documentation will save time (unclearspecifications are fixed at an early project state, system-architecture more clear,workflows clear,)

1.1.2 Documentation keeps software-quality at high levels:With documentation it is easy to check for various quality factors such as correctness(does software what customer wanted), reliability, efficiency (documentation might showmost efficient way at designing process), integrity, usability, maintainability (it must beeasy later on to make add-ons, patches, error-corrections, extensions), testability,flexibility, portability (transferring the software to other hardware/software environment),reusability (what parts of the software can be reused for other projects) andinteroperability (how to connect this software to other systems).

Further more this documented quality is visible to our customers, so they can see whatis in scope of the project and what is not. Documentations give customers a goodfeeling, regardless of whether they are going to use the documentation or not.

1.1.3 Documentation makes it easy to transfer projects:It is expected that the designers that work at project from the beginning have gained anextensive knowledge of how everything works, at least for the time being. Anyhow inmodern companies people come and go, projects are transferred or extended and soon.

So a good reason is to write documentation for other developers, who later will have tocome along without the extensive background that the designers have right now whileworking on it, or the email and verbal "documentation" the writer currently benefit from,or even the well-written specs and design documents which unfortunately have sincebecome out-of date, or worse, lost entirely.


7/30


Last change: AB 19/02/2010 07:49:00 7

1.2 Why does Specific-Group notdocument everything?There are various reasons but you can sum it up by Documentation costs time, costsmoney! Therefore Specific-Group tries to avoid over-documentation to save its

customer money and our developer time that can be put into more meaningful tasks.

1.2.1 Post-Documentation seldom makes sense:

Since documentation is mainly used during the process of software-design to helpdesigners to get a better idea of how everything works, it barely makes sense todocument this process ones all ideas are already established. It wont help thedevelopers any longer, since design process is over. Therefore documentation shall bedone beforethe software is done and also duringthe software-creation process, but notafterwards.

1.2.2 Documentation sometimes is academic:There are vast amounts of documentation styles, norms, tools and methods but only afew of them are really used in modern software-companies. While some of them mightactually have a use, others are unlikely even to be read by anyone but the creator, sincethey are either redundant with other documentation or too complicated to be understoodby anyone.

Therefore Specific-Group uses the most common methods, which have been proved invarious environments as samples of best practice and that are easy to understand by alldevelopers and even by readers who are not familiar to software-documentation.

1.2.3 Documentation methods not always make sense:

Not every documentation method can be used for every project. Since projects differ inrequirements and size, also the document-methods do. There Specific-Group takes adynamic approach to documentation, leaving unnecessary documentation out andconcentrating on the important depending on the project. (See last chapter for moredetails.)


8/30


Last change: AB 19/02/2010 07:49:00 8

1.3 Optional documentationApart from those reasons stated in the chapter before, if the customer wants to havecertain documentation, that is not included in the standard documentation of Specific-

Group, of course we will provide it. The hereby is just a recommendation and describesour default documentation which is done by default, but can be extended if needed (forwhat meaningful purpose ever) for the cost of additional working time (=> money) ofcourse. So the customer has to state it (before the development- start), if he wants moredocumentation than the default or if he likes to have his software post-documented.


9/30


Last change: AB 19/02/2010 07:49:00 9

2. METHODSIn the following chapter there is a list of documentation-standards that can be providedby Specific-Group. It does not include a very detailed description nor is it a tutorial howto create them, but it explains the use and the most important components.

Every method is introduced by a Description, which explains the general purpose ofthe method. This is followed by the Usage, which says when this method shall / must

be used for documentation. In Main Components and Examples you see the variousparts of the documentation-method with a very short description illustrated by examples.

Checklist for SPG shows which parts must be provided by the documentation whenusing this method. Finally under Further Information you might find additional links totutorials and more detailed descriptions.

Note: This document consists sometimes of different appearances of the samegraphics. This is to illustrate that you can use various styles, according to development

and documentation tools.


10/30


Last change: AB 19/02/2010 07:49:00 10

2.1 Entity-Relationship Diagrams

2.1.1 Description:ERD are data models used in analysis to describe the data requirements andassumptions in the system from a top-down perspective, so it identifies the data requiredby the business. An entity corresponds to a person, place thing, event, or concept aboutwhich we are interested in.

2.1.2 Usage:ERD are mainly used when designing a database. Drawing an ERD is generally a taskthat is done before designing the database to make database logic easier tounderstand. ERD give a very good overview of the database, so it will be also used fordocumentation purposes.

Note: Usually Specific-Group provides ERD in the functional specification (Pflichtenheft),but it can also be considered technical documentation, so it is listed here too.

2.1.3 Main Components and Examples:There are three basic elements in ER models:

Entitiesare the "things" about which we seek information (here in a square / boxes).

Attributesare the data we collect about the entities (here in round red).

Relationshipsprovide the structure needed to draw information from multiple entities(here in blue).


11/30


Last change: AB 19/02/2010 07:49:00 11

[Source]

Note:

Entities must be clearly defined in that way, that everybody understands exactly whatis being represented

Two entities whose information is somehow dependent on one another or connectedwith each other are said to have a relationship between them (e.g. character mayhave many items)

Relationships are evaluated in both directions to determine what type of relationshipexists

Cardinalities are described by numbers.

Entities should not be expressed in the plural

A single attribute for each entity is selected (or an arbitrary one is assigned) as being

the unique identifier for each occurrence of the entity (e.g. here character name toidentify the character). Mark those by underlining.

Optional: Instead of putting the attributes into the ERD you can also make tabledescriptions (see next method).

ERD can be also drawn by using UML-notification

2.1.4 Checklist for SPG:

An ERD must consist of:


12/30


Last change: AB 19/02/2010 07:49:00 12

Entities (with names in singular)

Relations between entities with cardinal numbers OPTIONAL (when table description is available): Attributes with unique keys

OPTIONAL: Attribute description

2.1.5 Further Information:

General Info

Tutorial


13/30


Last change: AB 19/02/2010 07:49:00 13

2.2 Table descriptions

2.2.1 Description:Table descriptions are used to define and list the attributes of an entity (see aboveERD), which is used within the database in a single table. This helps to avoid variableproblems, when accessing them later.

2.2.2 Usage:When designing the database tables will also be in paper-form. Most databasemanaging tools provide a printout of the database anyhow so that this should be noproblem at all drawing them directly out of the tools. Print one table per entity and alsoan overview if useful. Table descriptions must be used, especially when the attributesare not shown in the ERD.

Note: Usually Specific-Group provides table descriptions in the functional specification(Pflichtenheft), but it can also be considered technical documentation, so it is listed heretoo.

2.2.3 Main Components and Examples:Tables must show as much information of the attributes as possible, therefore providingattribute-name, datatype, datatype-length, primary keys, foreign keys, unique keys andsome explanatory comments.

Example:Table of Entity Person

Attribute Datatype

Length PK FK UK Comment / Translation

PersonID Integer 10 X X Database ID that defines a Person

PersonNumber Integer 50 X Shall be given from the system (auto-increase) when new Person

PersonName String

PersonName2 String

PersonStreet String

PersonZIP

DeliveryConditionsID

Integer X X

PayingConditionsID Integer X X

VAT String 20 X

Note:Attribute is the name of the attribute in the database, PK means primary key, FK foreignkey, UK unique key, Comment you will find comments and translations.


14/30


Last change: AB 19/02/2010 07:49:00 14

Sometimes an attribute-overview of all table descriptionsmight be useful:

Here you can see in one view how the tables are connected. This documentation isusually also drawn directly out of the database development-tool.

2.2.4 Checklist for SPG:Table descriptions must consist of the following:

Attribute IF KNOWN (later on it must be provided): Data-type

IF KNOWN (later on it must be provided): Length

Primary key Foreign key

UK unique key OPTIONAL: Comments

OPTIONAL: Attribute overview


None


15/30


Last change: AB 19/02/2010 07:49:00 15

2.3 Class diagram

2.3.1 Description:A class diagram is a type of static structure diagram that reflects the structure of asoftware-system by showing the system's classes, their methods, attributes, and therelationships between the classes. It gives the coder an overview of the whole systemwithout going to far into detail.

2.3.2 Usage:Use a class diagram especially when coding object oriented. Since the class diagramscan be usually be derivated automatically from the development kit they are easily andquickly done. Nonetheless they are very helpful to see which classes exist and what dothey do.

2.3.3 Main Components and Examples:

2.3.3.1 Class-appearance:

[Source]

Note:Account is a supertype / generalization of the subtypes CheckingAccount,SavingAccount, CreditcardAccount. Each class in the class diagram may be capable ofproviding certain functionalities. These functionalities provided by the class are termed"methods" of the class. Apart from this, each class may have certain "attributes" thatuniquely identify the class.


16/30


Last change: AB 19/02/2010 07:49:00 16

2.3.3.2 Scaffolding:To make the classes and documentation more readable just useful information shall beprovided. Therefore class diagrams are done without scaffolding by leaving awayuninteresting methods/attributes:

[Source]

2.3.3.3 Relationships:The class diagram also shows the relationship or association between the classes canbe either an "is-a" or "has-a" relationship.

2.3.3.4 Associations:You can also insert association between the classes. A direction indicator can also beused to show the direction of the name, but is not necessary if the direction is obvious:

[Source]


17/30


Last change: AB 19/02/2010 07:49:00 17

2.3.3.5 Class-Descriptions:Then you can add class-descriptions to the diagram or write them below if that is easier.Here examples for both:

[Source]


18/30


Last change: AB 19/02/2010 07:49:00 18

Example with a text below class diagram:Article Management class diagram.

MainForm- Main Form of the Article Management tool.ArticleFormPersister class which serialize form user settings (size,location, column width, grid width) to the isolated storage.ArticleFormPersistencesettings class that defined with serializableattribute and which contains properties which are serialized byArticleFormPersister.Logo class which is responsible for correct displaying of the logos panel.It changes sizes of the logos proportionally when form size is changed.GridDataTable- A grid control which displays data from a DataTable.Configuration - Provides access to params stored in configuration databasetable.Constants Contains color constants used in the application.

ExceptionHandler Contains exception handlers used by all of theapplications. Writes all errors with detail information to the error log anddisplays an error or a warning message to the user if it is needed.ResourceManager- Reads resource strings from language.cfg file.

SqlServerUtility- Helper class which provides connection string. Also it isdesigned to share sql-ralated methods used from several applications.UIHelper contains routines used to show dialogs in the application.


19/30


Last change: AB 19/02/2010 07:49:00 19

2.3.4 Checklist for SPG:A Class Diagram must consist of:

Graphical representation of classes (names) Methods of classes

OPTIONAL (if useful): class-attributes OPTIONAL (if useful): visibility of methods and attributes

Relationship between classes (generalization, abstract classes,) Associations with role name and multiplicity OPTIONAL: Aggregation and Compositions Short-Description of Classes

OPTIONAL: Other UML Components (see Links)


General

About Relationships and Aggregations


20/30


Last change: AB 19/02/2010 07:49:00 20

2.4 Package diagram (class packages)

2.4.1 Description:Gives an overview, what packages exist and what classes are included in that package.Also, it is documented, how the packages interact (predefined edges).

2.4.2 Usage:This is used at very complex projects, which include packages (or maybe modules ofexternal source or source reuse).


[Source]

2.4.4 Checklist for SPG:A Package Diagram must consist of:

Name of packages Interaction between package


General

Tutorial


21/30


Last change: AB 19/02/2010 07:49:00 21

2.5 Sequence diagram

2.5.1 Description:A sequence diagram shows as parallel vertical lines different processes or objects thatlive simultaneously, and, as horizontal arrows, the messages exchanged between them,in the order in which they occur. Therefore these diagrams are used to seedependencies from objects on the bases of messages (method-calls).

2.5.2 Usage:This can be used to check the logic of a usage scenario. It helps to step throughinvocation of the operations defined by the classes.


[Source]

Note:Only the most important classes should be included (see above). Even more, to avoidoverloading of the diagram, for each important usecase, an extra diagram must bedrawn

2.5.4 Checklist for SPG:A Sequence Diagram must consist of: Name of classes Interaction between classes (methods) Timelines


22/30


Last change: AB 19/02/2010 07:49:00 22


General Information

2.6 Dataflow Diagram

2.6.1 Description:Dataflow diagrams show how data is passing within the system. In other words, it showswhat goes in, how it is changed, what comes out.

2.6.2 Usage:They are used for illustration of dataflows within the system, when they are difficult tounderstand.

2.6.3 Main Components and Examples: Squares representing external entities, which are sources or destinations of data.

Rounded rectangles representing processes, which take data as input, do somethingto it, and output it.

Arrows representing the data flows, which can either be electronic data or physicalitems.

Open-ended rectangles representing data stores, including electronic stores such asdatabases or XML files and physical stores such as or filing cabinets or stacks ofpaper.

[Source]

2.6.4 Checklist for SPG:A Sequence Diagram must consist of: Origin of data

Input of data (what data goes into a certain entity) Output of data (what data goes out a certain entity)

How is it changed (methods used)


23/30


Last change: AB 19/02/2010 07:49:00 23


General information

Tutorial

2.7 Workflow Diagram

2.7.1 Description:

Workflow diagrams show how the system handles certain use-cases. They are not on atechnical level rather offer an abstract view of decisions within the system. They showwhat has to be done in certain cases.

2.7.2 Usage:They are used for illustration of workflows within the system, if they are difficult to

understand. Use them especially when they are a lot of decisions on the way, on whichthe next state depends.

Note: Usually Specific-Group provides workflow diagrams in the functional specification(Pflichtenheft), but it can also be considered technical documentation, so it is listed heretoo.


24/30


Last change: AB 19/02/2010 07:49:00 24


Squares represent states

Arrows representing way to the next state

Decisions are marked by sidewarded rectangles

2.7.4 Checklist for SPG:A Workflow Diagram must consist of:

Origin state of data Arrows that mark the timeline

Decisions on with the next state depends

End of data OPTIONAL: How is it changed (methods used)


None


25/30


Last change: AB 19/02/2010 07:49:00 25

2.8 Source code Commenting

2.8.1 Description:Source Code Commenting is essential to maintain code. It offers explanations to sourcecode that is difficult to understand. Source code commendation helps to see how thewhole system works (when all classes and modules are described) as well as very singlecomplicated algorithms in detail work. Therefore the coder shall not write codecomments and code documentation only for himself.

2.8.2 Usage:It is expected that while the programmer is writing the code, he has gained an extensiveknowledge of how it works, at least for the time being, and the additional source codedocumentation and other source code comments beyond the raw source code itself mayfeel like a big fat waste of time.

So the real purpose is to write them for the poor developer, who years later will have tocome along trying to work on this code without the extensive background that the coderhas right now while working on it, or the email and verbal "documentation" the writercurrently benefit from, or even the well-written specs and design documents whichunfortunately have since become out-of date, or worse, lost entirely.

It is not advise-able to comment source code after the coding, but rather while doing so.

2.8.2.1 Usage-Guides: Use source code commendation that is compatibly with some kind of documentation

tool (like Doxygen, Javadoc,). This saves a lot of time later on to automaticallycreate the source documentation. Sometimes the documentation can than bedirectly taken out of the development tool. Therefore coders must stick to the normsof the documentation-tool. (Note that in the following examples Doxygen syntax isused. Of course other documentation tools require different syntax that shall andmust be used.)

Just like for the code itself, the code owner picks the source code documentationstyle. When modifying code with pre-existing source code documentation/comments,following the existing examples and formatting is to be done.

When modifying existing code, it is critically important that any associated sourcecode documentation be updated and kept in sync. Without this, the documentationbecomes unreliable, unusable and the code drifts into bit-rot. For this reason, whencoders are writing source code documentation, they have to attempt to write it in alow-maintenance style while still providing the most important/useful information.

The source code must not be bloated with documentation. It becomes difficult to

maintain. Clarity and conciseness are keys! In practice, this clarity will inevitably alsoaide the thinking processes and design skills. It is possible to add so much sourcecode documentation you can't see the forest for the trees and the code itselfbecomes obscured and difficult to follow. It must not be over-done!


2.8.3.1 Comments:


26/30


Last change: AB 19/02/2010 07:49:00 26

When locating them on the same line as the code, the recommended style is ///< asshown:#define FOOBAR_QLEN 2048 ///< Max size of each FooBar queue

Single-comments prior to the item being documented should use /// as shown:

/// Max size of each FooBar queue#define FOOBAR_QLEN 2048

Multi-line comments should be placed just prior to the item being documented:/*** \brief FooBarCache - Implements a per-thread FooBar cache.** Implements a per-thread FooBar cache (or per-process, depending on the* platform) to reduce mutex contention in the shared FooBar allocator.*/class FooBar{...

Prefer using /** to /// for multi-line comments for consistancy.

2.8.3.2 Descriptions:Each method/function in the source code should contain a brief, one-line, description.

IMPORTANT!!! Each method/function definition in the source code should also

contain a description of the function's parameters (if any), return value, and if

necessary, an additional verbose description. Use of parameter qualifiers such as"[in]", "[out]" and "[in/out]" is recommended.

An example of this and the previous guideline is:/*** \brief FooBarGet - Allocate a FooBar from the FooBar cacheif available* \param ulSize [in] Size of FooBar to retrieve from the FooBar cache.* \param FooBar* [out] Bucket that the FooBar should be retrieved from.* \param CPool* [in/out] Location of FooBar pool. May be modified if pool

grows.* \return Success/Failure.** FooBarGet - look for a FooBar in our FooBar cache, which contains* FooBar objects handed to us by other FooBar instances.** \par* Note how we can grab FooBars from the FooBar Queue without the need for* using a mutex. This is very important! Only the owner of this* FooBar object is allowed to modify m_ulFooBarHead.*/inline char*FooBarCache::FooBarGet(size_t ulSize, UINT32 ulBucket){...

Also define within methods, classes, algorithms when something is not easy to readfrom the code, why this is written in the way it is:

Example bad:// Nothing hereif (base == 1) {int basePeriodIndex = event.getRequestParameter("basePeriod",0);

Example good://base == 1 is when RelativeTimePeriod is used//in case of RelativeTimePeriod is used, the parameters of the BasePeriod aresetif (base == 1) {int basePeriodIndex = event.getRequestParameter("basePeriod",0);


27/30


Last change: AB 19/02/2010 07:49:00 27

2.8.3.3 Avoid senseless comments:Dont do senseless documentation, when it is possible to see it directly out of the code.

Example:/*** The RemoteExtensionClass extension class.*/private static RemoteExtensionClass extClass;

2.8.3.4 To do Items:When noting "to-do" items in comments, it is recommended that you consider using the\todo identifier so these items are easily indexed / searchable.

2.8.4 Checklist for SPG:Source Code Commendation must have:

Documentation-tool / development-tool compatible comments All complex algorithms, methods, variables are explained (when source code reading

would take much time or is not easy to understand)

Senseless comments avoided Update of changed items


Doxygen


28/30


Last change: AB 19/02/2010 07:49:00 28

3. TECHNICAL DOCUMENTATION USAGEAs already stated in the introduction this guide tries to avoid over-documentation thatwould keep coders busy without any real use. Specific-Group offers therefore a time-based and content-based approach when to use the repertory of available methodsintroduced in the chapter before.

Anyhow, note that it is always the designers decision if something makes sense todocument or not. Some things require more documentation while others do less. Thisguide is anyhow to be seen as a general standard for Specific-Group and therefore mustbe taken as reference.


29/30


Last change: AB 19/02/2010 07:49:00 29

3.1 Time GuideThe key value of documentation is during the design process of the software.Documentation of design-issues seldom makes sense once they are already in the

system and done. For example it is of no use to draw sequence diagrams, when thesequences are already implemented.

This concludes that first documentation has to be done, later you can startimplementing (for the most methods of documentation).

Therefore use this grid to see when the methods make sense in the timeline of a project.Doing documentation-methods for something which time has already passed generallyis a waste of money and should be avoided.

Method /

Timeline

Entity

-

Relationship

Diagrams

Table

descr

ipt-ions

Class

diagram

Packa

ge

diagram

Sequence

diagram

Dataflow

diagram

Workflow

Diagram

Sourc

eCode

Document-

ation

1) Process of

Functional

specification

Creation

X X X

2) Process of

Software-

Design /

Architecture-

Design

X(Update)

X (X) X X

3) During

Code-

generation

X(Update)

X(Update)

X

4) Post Code-generation

(Software done

coding, Project

End =>

Archive)

X(finalDocumentation)

X(finalDocumentation)

Note: Generally the documents that are in Phase 1 are already done in the technicalspecification. So the coder has only to do them if they are not available there.


30/30

3.2 Reasonability GuideNot every method makes sense for every project. Therefore this table offers a list whichmethod has to be done under which circumstances. So unnecessary documentation is

avoided again. This is a collection of all data, that has been mentioned within Usage inthe methods-chapter (See there for more detailed descriptions).

Method /

Property

Entity-

Relationship

Diagrams

Table

descript-ions

Class

diagram

Package

diagram

Sequence

diagram

Dataflow

diagram

Workflow

Diagram

SourceCode

Document-

ation

Software (SW)

uses a

Database

X X

Code is object-

orientedX

(X)when

needed

(X)whe

n

needed

X

Code uses lots

of packages

and external

classes

(X)when

efficientX

SW has

timelines that

are difficult to

understand

X

(X)whenneed

ed

Use-cases

workflow have

decisions that

are difficult to

understand

(X)whenneed

ed

X

SW has code

(*smile* - this

must always be

done!)

X

Documents

Technical Documentation StandardsV1.3