March 12, 2008 Technical Documentation by Techies Dr. Partha Pratim Das Interra Systems (India) Pvt. Ltd.
Jun 11, 2015
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