INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of...
-
Upload
kadin-pattison -
Category
Documents
-
view
220 -
download
0
Transcript of INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of...
![Page 1: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/1.jpg)
INSE - Lecture 16
Documentation Configuration Management Program Support Environments Choice of Programming Language
![Page 2: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/2.jpg)
Documentation
![Page 3: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/3.jpg)
Purpose
Documentation should tell us about the thing being documented…
...not about the person who wrote it! (But it often does…)
![Page 4: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/4.jpg)
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
![Page 5: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/5.jpg)
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).
![Page 6: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/6.jpg)
Organize the maintenance docs:
![Page 7: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/7.jpg)
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.
![Page 8: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/8.jpg)
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.
![Page 9: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/9.jpg)
Documentation tools
word processors; index generators; systems for graphic display of design
descriptions; cross-referencers and other code-analysis
tools; ...
![Page 10: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/10.jpg)
Configuration Management
![Page 11: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/11.jpg)
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...
![Page 12: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/12.jpg)
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.
![Page 13: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/13.jpg)
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...
![Page 14: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/14.jpg)
Program Support Environments
![Page 15: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/15.jpg)
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.
![Page 16: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/16.jpg)
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….
![Page 17: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/17.jpg)
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; ...
![Page 18: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/18.jpg)
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.
![Page 19: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/19.jpg)
Choosing an appropriate programming language for the project
Issues: consequences of the choice; modular languages.
![Page 20: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/20.jpg)
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.
![Page 21: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/21.jpg)
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.
![Page 22: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/22.jpg)
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.
![Page 23: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/23.jpg)
Prejudices
Ada programmers think that…
C programmers think that…
… C is …
… anarchy
… freedom
… Ada is …
…organization
… bondage
foolish!
![Page 24: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/24.jpg)
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!
![Page 25: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/25.jpg)
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.
![Page 26: INSE - Lecture 16 Documentation Configuration Management Program Support Environments Choice of Programming Language.](https://reader035.fdocuments.us/reader035/viewer/2022062417/551b3455550346dd1a8b4ff9/html5/thumbnails/26.jpg)
© C Lester 1997-2003