March 12, 2008

Technical Documentation

by Techies

Dr. Partha Pratim DasInterra Systems (India) Pvt. Ltd.

10-Mar-08 22

Agenda

• Motivation

• What is Technical Documentation?

• Objectives

• Planning is Critical

• Document Planning Ideas

• Language / Style Tips

• 4 C’s of Technical Documentation

10-Mar-08 33

Motivation

• To improve the efficiency and effectiveness of Technical Documentation by Engineers

10-Mar-08 44

What is Technical Documentation?

• Technical Documentation is the process of conveying information about Technology to an intended Audience through a Document.

10-Mar-08 55

Objectives• Creating documents in

– a specialized and structured form• Communicating to convey

– a particular piece of information to – a specific audience for – a specific reason

• Gathering – relevant information from the experts and presenting to audience

• Translating – technical ideas into words to make it understandable to specific

audience• Explaining

– complex information in clear & simple language

10-Mar-08 66

Planning is Critical• Central to Planning is asking Questions:

– What type of document do you want to create?• RFP: Request for Proposal• SRS: System Requirements Specification / Functional Specs• Design Document

– High Level– Low Level

• Test Plan• User Guide / Instruction Manual• Data Sheet• SoW: Statement of Work• NDA: Non-Disclosure Agreement• White Paper• Website• Blog• Presentation• Email• …

10-Mar-08 77

Planning is Critical

• Central to Planning is asking Questions: – What is the purpose of the document?

• Capture unstructured thoughts (RFP / SRS)• Move down on the hierarchy of Abstraction:

– Spec HLD LLD As Built

• Enumeration of Scenarios (Test Plan)• Define Water-tight Framework (SoW / NDA)• Just Present some Ideas (White Paper)• Brag (Blog)• …• Pleasure of Reading• Pleasure of Writing• …

10-Mar-08 88

Planning is Critical• Central to Planning is asking Questions:

– Who you are writing for?• Section of People

– Customer– Internal Audience– Peers

• Type of People– Engineers– Managers– Marketing

• Level of People– Naïve– Informed– Knowledgeable– Expert– Guru

10-Mar-08 99

Planning is Critical

• Central to Planning is asking Questions: – What should be the content of the document?

1. Define a ToC

2. Outline every Section

3. Check for Dependency

4. Refine ToC

5. Expand every Section

6. Repeat Steps 3 through 5

Form is important; but Content is UltimateForm is important; but Content is Ultimate

10-Mar-08 1010

Planning is Critical

• Central to Planning is asking Questions: – What should be the approximated page count

for the document?– What software / tools to be used?– …

10-Mar-08 1111

Document Planning

• Decide the objective of the document – Every document needs a single clear objective. – The objective should be as specific as possible. – Ideally, this should be in one sentence. – Example:

• Design Document for Command Line Parser

• Objective:– “To present the Design of a Generic yet Lightweight

Command Line Parser for use in various applications in OVC”.

10-Mar-08 1212

Document Planning

Reader Domain Knowledge

Software Knowledge

Relevance

Project Manager @ NFT High Low Medium

Software Engineer @ Interra Low High High

Application Engineer @ HTL Low Low Medium

• Have a specific reader in mind – Always. – The reader is intelligent but uninformed.

– State the reader profile up front.

– Example:• Design Document for Command Line Parser

• Reader Profile:

10-Mar-08 1313

Document Planning

• Decide what information to include. – Frame of Reference: Objective– List Areas to Cover:

10-Mar-08 1414

Document Planning• Decide what information to include.

– ToC:• Command Mode

– Direct– Indirect

• Architecture• Generic Command Parser

– Generic Command Structure– Parsing Algorithm

• Application-Specific Command Parser– Application-Specific Command Structure– Instantiating Commands

• Error & Exception Handling– Missing Command File– Undefined Commands– Illegal Command Parameters– Programming Exceptions

• Threaded Behavior• How to Test (Unit Tests)• References

10-Mar-08 1515

Document Planning

• Identify Assistance– Good Dictionary– Good Reviewer– . . .

10-Mar-08 1616

Language / Style Tips

• Avoid the following infractions:– Typos & Spelling Errors (Spell-check).– Grammatical Errors (Grammar-check).– Use of passive voice (search for is, are, were,

by, etc.); • replace with the active voice

– Use of future tense (search for will); • replace with the present tense

– Use of conditional tense (search for ould); • replace with the present tense

10-Mar-08 1717

Language / Style Tips

• Avoid the following infractions:– Use of contractions (n’t and ’ve);

• replace with full words

– Use of non-parallel construction (bulleted lists); • ensure that the first word of each list item is of the same type

(noun, verb)

– Use of unclear antecedent ("This"); • ensure that "This" is followed by a noun and not a verb

– Use of and/or; • replace with ". . . or . . ., or both"

– Use of forbidden words– Broken links.

10-Mar-08 1818

4 C’s of Technical Documentation

• Clarity – Can it be easily understood by the audience?

• Comprehensiveness – Is all of the necessary information present?

• Conciseness – Is it clear without excess verbiage?

• Correctness – Is grammatically correct?– Is it technically sound?– Does it follow conventions?

10-Mar-08 1919

References

• Articles in Interra TechPubs Site: http://techpubs.noida.interrasystems.com/

10-Mar-08 2020

Credits / Acknowledgements

• Sabarni Guha – For the first draft of this Presentation

10-Mar-08 2121

Thank You