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.
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).
MoD JSP188 doc tn. 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; ...
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...
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 d 3 is common; Up to 10,000 lines (or less) - programmer can hold everything in background memory –up to 10 lines/day d 3 is common; But in modular languages, only interfaces need be known –up to 20 to 40 lines/day d 3 is common.
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.