INSE - Lecture 16

Documentation Configuration Management Program Support Environments Choice of Programming Language

Documentation

Purpose

Documentation should tell us about the thing being documented…

...not about the person who wrote it! (But it often does…)

Audiences

various audiences– consequently…

» different kinds of document» different styles.

System Evaluator: Functional Description

System Evaluator: Functional Description

System Programmer: Installation Document System Operation Doc

System Programmer: Installation Document System Operation Doc

Novice User: Introductory Manual

Novice User: Introductory Manual

Experienced User: Reference Manual

Experienced User: Reference Manual

The right level of document... Fit the vocabulary & complexity of a document to

it’s audience: use the reader’s jargon -

– computing jargon for internal documents;– application jargon for user documents;

clever words & phrasing for clever users (only!) fit the purpose of the text - e.g. -

– intro text should avoid fine detail (but repeat key points from multiple viewpoints);

– reference text should include every significant point (once and once only).

Organize the maintenance docs:

MoD JSP188 doctn. structure

1/ basic outline & system structure, breakdown; s/w for each facility; supporting info;

2/ functional description of each task & data area; timing info;

3/ functional description of each process & data structure;

4/ code, test criteria, supports such as location of firmware.

Documentation standards Company “look and feel” rules; checklists to promote completeness; consistency rules when there are multiple

authors.

Such standards can vary enormously -– it’s more important to have a reasonable

standard than exactly what it says…– but the documenter needs to be flexible.

Documentation tools

word processors; index generators; systems for graphic display of design

descriptions; cross-referencers and other code-analysis

tools; ...

Configuration Management

Problem:

Keeping track of all the requirements documents specification documents design documents source files object files test drivers test data debugging records …

is a major task in a large project...

...which gets worse when each of those exists in many versions and variants...

Definitions: A version may be replaced by a later version;

A variant may be one of many parallel variants, all being "the latest version of that variant".

Large project => usually multiple versions & variants of each software component (maybe hardware components also).

One version/variant may depend on certain versions/variants of other components.

So...

this is a major administration problem in large projects;

there are management issues, but more than that…

… we need something to help us keep track of it all.

Which leads us to...

Program Support Environments

PSE = big brother of an IDE A PSE is an integrated workbench of

tools for programmers and their management

It also is a “database” of all of the documents of a project

= specs, design docs, code, test plans, test records, debugging records… etc. …

the audit trails and the dependencies between the

documents.

Programmers view of a PSE design tools; compiler(s) editors(s) linker(s) tools to manipulate

object files generalized test

harnesses debugger(s)

source-manipulation tools:– cross-referencers– profilers– indenters– ?program provers

documentation tools programs to detect

portability problems

with communication between all the tools….

Team-leader’s view

A database that holds all the project documents; cross-indexes them; audit-trails them; helps in configuration management; helps to mile-stone the progress of the project; reports symptoms of team-members who may

be in trouble; ...

The PSE interface

A single PSE may be hosted on multiple platforms, so…

the project is platform-independent; the staff are platform-independent (I.e. can

move between hardware & O.S.s with minimal retraining.

Choosing an appropriate programming language for the project

Issues: consequences of the choice; modular languages.

Consequences Some languages are good for programs that

need to be “close to the hardware”; Some languages are good for big programs; Some for high-reliability programs; Some are good for evolutionary development; Some are good for quickly-written small

programs…

No language is good for all of those– they are conflicting objectives.

SO A CHOICE IS NEEDED... … for each project; … sometimes, different choices for different

parts of a single project.

1/ to make that choice prudently, you need moderate familiarity with multiple languages;

2/ and then do make that choice– don’t just “use what we used last time;– run any re-training your choice demands.

Modular languages (incl.. OO) Up to 100 lines (or less) - programmer can

hold everything in foreground memory– up to 50 lines/day d3 is common;

Up to 10,000 lines (or less) - programmer can hold everything in background memory– up to 10 lines/day d3 is common;

But in modular languages, only interfaces need be known– up to 20 to 40 lines/day d3 is common.

Prejudices

Ada programmers think that…

C programmers think that…

… C is …

… anarchy

… freedom

… Ada is …

…organization

… bondage

foolish!

After this lecture - documentation

Look at other people's documentation– analyze what are the good features and

bad (or missing) features;– analyze how well it fits the need of the

audience; Aim to do better yourself!

After this lecture – CM & language

Be prepared for the extra organizing needed for large projects;

Use sensible tools to keep track of size.

For all projects, make a sensible and well-timed choice of language(s) to use.

© C Lester 1997-2003