Technical Documentation By Techies


Published on

Techies make a mess of TechPubs. Why? Explains this 2008 presentation.

Published in: Technology
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • In the background of challenges faced by the NFT engineers in OVC project, this discussion was planned. Madhubanti, Debanjan, Sudakshina, Debarshi, Prasun, Anindita, Sujay and Swagat participated in the two-hours long session. A more refined, generic and developed form of this presentation may be made to a wider section of junior engineers at Interra.
  • Interact with the audience to stretch their imagination about document forms and the collation of the forms to the purpose of documentation expressions. Highlight that many common forms are missing: Book Dissertation Technical Report … Explain some of the less common terms like White Paper, Blog: White Paper (Wiki): A white paper is an authoritative report or guide that often addresses problems and how to solve them. White papers are used to educate readers and help people make decisions. They are used in politics and in businesses. Blog (Wiki): A blog (a portmanteau of web log ) is a website where entries are commonly displayed in reverse chronological order. "Blog" can also be used as a verb, meaning to maintain or add content to a blog. A BLOG is a publication of personal thoughts, experiences, and web links. It is updated frequently and is usually a mixture of what is happening in a person's life and what is happening on the web or in the media. ... Socialize the notion that documents could be non-textual in form – like UML to capture spec to HLD or Program Code to capture lower than LLD.
  • Wish to Specification is the process of “Capture unstructured thoughts”. Detail on Moving down the Abstraction Hierarchy: It is a transformational process where every stage adds more specifics without compromising the precision of the higher layers of abstraction. HLD can be in various forms. One common is to use UML. Of course, the tools (Rational Rose / Raphsody) are costly. Discuss the example of using ER Diagrams (TEACHER-TEACHES-STUDENTS) as HLD. HLD does not (should not) cover specifics of Platform, Language, etc; yet should get a lot more concrete than the Specification stage. Example: If we need to maintain a list of name-value pair; we should talk about a Symbol Table in the HLD. It’s not okay to talk about std::map<type,..> LLD can be in various forms. One common is to use Codes. Discuss the example of using Relational Language (SQL) as LLD. LLD should get specific in terms of Platform, Language, Configurations etc; yet must remain a lot higher than the actual code. However, it can use codes as illustrations. Example: For a list of name-value pair; it’s okay to talk about std::map<type,..> in LLD. Socialize the notions of “As Built Drawings” from Construction Engineering. There is not much software equivalent for it. Wish: Owner needs an 2BHK Spec: Architect makes Plan and Elevation Drawings. HLD: Various engineering groups prepare respective drawings – Civil Drawing, Electrical Drawing, Plumbing Drawing, Sewage Drawing etc. LLD: Civil group puts the analysis of structures, Electrical group elaborates cabling drawing & power estimates etc. As Built: Reverse engineer the above drawings in terms of what has actually been done. Deviate from core documentation process issues and delve into software process issues. We often use an MLD (Mid-Level Design) or ILD (Interim / Interra Level Design) in lieu of HDL-LLD pair. This is a compromise; but often a practical choice.
  • This is the meat of documentation and naturally deals primarily with Content than Form. There is no generic formula for it. The above is a (Recursive) Divide-Conquer approach to structurally decompose the Design (and ensuing Documentation) problem into manageable units (Humans, at a time, can handle only up to 5 / 6 items). Later we’ll add more workshop-items here for illustration and workout.
  • Is Page Count (like LoC) a stupid metric? Probably not. If I know that a CEO needs to read a document; I must keep it to a page (at the most) or a one-page Executive Summary to it. We have covered MS-WORD as the tool already.
  • Parse the example Objective and justify the choice of words: To present the “ Design” of a “ Generic” yet “ Lightweight” “ Command Line Parser” for use in “ various applications in OVC” Objective should be so framed that dropping a single word would change the scope and slant of the document.
  • Explain Intelligence Uninformed the use of Relevance – will set the tone. (Sudakshina) How does a document satisfy a variety of Reader Profiles at the same time? Documents are made multi-part: A Doctoral Dissertation has – An Abstract, A Synopsis and The Report A Technical Book has – A Foreword, A Preface, An Introduction and The Chapters. Documents are made multi-perspective
  • Core of designing a ToC is to try to clone some Software / Design / Document that is close to the current requirements. Where did we see Command Line? GCC Make GDB does not qualify as it takes commands through the interpreter. Explain this ToC. Encourage the audience to identify the defects in the ToC Does not define what is a Command Line. Someone may confuse Command Interpreter of a Software with the Command Line. “ Architecture” is the pivotal section and should be expanded further. Example Applications needs elucidation. No section should for Assumptions / Open Issues …
  • “Dictionary” used in a generic sense: English Language Design Patterns Cell Library Reusable Designs / Codes
  • Technical Documentation By Techies

    1. 1. March 12, 2008 Technical Documentation by Techies Dr. Partha Pratim Das Interra Systems (India) Pvt. Ltd.
    2. 2. Agenda <ul><li>Motivation </li></ul><ul><li>What is Technical Documentation? </li></ul><ul><li>Objectives </li></ul><ul><li>Planning is Critical </li></ul><ul><li>Document Planning Ideas </li></ul><ul><li>Language / Style Tips </li></ul><ul><li>4 C’s of Technical Documentation </li></ul>
    3. 3. Motivation <ul><li>To improve the efficiency and effectiveness of Technical Documentation by Engineers </li></ul>
    4. 4. What is Technical Documentation? <ul><li>Technical Documentation is the process of conveying information about Technology to an intended Audience through a Document. </li></ul>
    5. 5. Objectives <ul><li>Creating documents in </li></ul><ul><ul><li>a specialized and structured form </li></ul></ul><ul><li>Communicating to convey </li></ul><ul><ul><li>a particular piece of information to </li></ul></ul><ul><ul><li>a specific audience for </li></ul></ul><ul><ul><li>a specific reason </li></ul></ul><ul><li>Gathering </li></ul><ul><ul><li>relevant information from the experts and presenting to audience </li></ul></ul><ul><li>Translating </li></ul><ul><ul><li>technical ideas into words to make it understandable to specific audience </li></ul></ul><ul><li>Explaining </li></ul><ul><ul><li>complex information in clear & simple language </li></ul></ul>
    6. 6. Planning is Critical <ul><li>Central to Planning is asking Questions: </li></ul><ul><ul><li>What type of document do you want to create? </li></ul></ul><ul><ul><ul><li>RFP: Request for Proposal </li></ul></ul></ul><ul><ul><ul><li>SRS: System Requirements Specification / Functional Specs </li></ul></ul></ul><ul><ul><ul><li>Design Document </li></ul></ul></ul><ul><ul><ul><ul><li>High Level </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Low Level </li></ul></ul></ul></ul><ul><ul><ul><li>Test Plan </li></ul></ul></ul><ul><ul><ul><li>User Guide / Instruction Manual </li></ul></ul></ul><ul><ul><ul><li>Data Sheet </li></ul></ul></ul><ul><ul><ul><li>SoW: Statement of Work </li></ul></ul></ul><ul><ul><ul><li>NDA: Non-Disclosure Agreement </li></ul></ul></ul><ul><ul><ul><li>White Paper </li></ul></ul></ul><ul><ul><ul><li>Website </li></ul></ul></ul><ul><ul><ul><li>Blog </li></ul></ul></ul><ul><ul><ul><li>Presentation </li></ul></ul></ul><ul><ul><ul><li>Email </li></ul></ul></ul><ul><ul><ul><li>… </li></ul></ul></ul>
    7. 7. Planning is Critical <ul><li>Central to Planning is asking Questions: </li></ul><ul><ul><li>What is the purpose of the document? </li></ul></ul><ul><ul><ul><li>Capture unstructured thoughts (RFP / SRS) </li></ul></ul></ul><ul><ul><ul><li>Move down on the hierarchy of Abstraction: </li></ul></ul></ul><ul><ul><ul><ul><li>Spec  HLD  LLD  As Built </li></ul></ul></ul></ul><ul><ul><ul><li>Enumeration of Scenarios (Test Plan) </li></ul></ul></ul><ul><ul><ul><li>Define Water-tight Framework (SoW / NDA) </li></ul></ul></ul><ul><ul><ul><li>Just Present some Ideas (White Paper) </li></ul></ul></ul><ul><ul><ul><li>Brag (Blog) </li></ul></ul></ul><ul><ul><ul><li>… </li></ul></ul></ul><ul><ul><ul><li>Pleasure of Reading </li></ul></ul></ul><ul><ul><ul><li>Pleasure of Writing </li></ul></ul></ul><ul><ul><ul><li>… </li></ul></ul></ul>
    8. 8. Planning is Critical <ul><li>Central to Planning is asking Questions: </li></ul><ul><ul><li>Who you are writing for? </li></ul></ul><ul><ul><ul><li>Section of People </li></ul></ul></ul><ul><ul><ul><ul><li>Customer </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Internal Audience </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Peers </li></ul></ul></ul></ul><ul><ul><ul><li>Type of People </li></ul></ul></ul><ul><ul><ul><ul><li>Engineers </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Managers </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Marketing </li></ul></ul></ul></ul><ul><ul><ul><li>Level of People </li></ul></ul></ul><ul><ul><ul><ul><li>Naïve </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Informed </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Knowledgeable </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Expert </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Guru </li></ul></ul></ul></ul>
    9. 9. Planning is Critical <ul><li>Central to Planning is asking Questions: </li></ul><ul><ul><li>What should be the content of the document? </li></ul></ul><ul><ul><ul><li>Define a ToC </li></ul></ul></ul><ul><ul><ul><li>Outline every Section </li></ul></ul></ul><ul><ul><ul><li>Check for Dependency </li></ul></ul></ul><ul><ul><ul><li>Refine ToC </li></ul></ul></ul><ul><ul><ul><li>Expand every Section </li></ul></ul></ul><ul><ul><ul><li>Repeat Steps 3 through 5 </li></ul></ul></ul>Form is important; but Content is Ultimate
    10. 10. Planning is Critical <ul><li>Central to Planning is asking Questions: </li></ul><ul><ul><li>What should be the approximated page count for the document? </li></ul></ul><ul><ul><li>What software / tools to be used? </li></ul></ul><ul><ul><li>… </li></ul></ul>
    11. 11. Document Planning <ul><li>Decide the objective of the document </li></ul><ul><ul><li>Every document needs a single clear objective. </li></ul></ul><ul><ul><li>The objective should be as specific as possible. </li></ul></ul><ul><ul><li>Ideally, this should be in one sentence. </li></ul></ul><ul><ul><li>Example: </li></ul></ul><ul><ul><ul><li>Design Document for Command Line Parser </li></ul></ul></ul><ul><ul><ul><li>Objective: </li></ul></ul></ul><ul><ul><ul><ul><li>“To present the Design of a Generic yet Lightweight Command Line Parser for use in various applications in OVC”. </li></ul></ul></ul></ul>
    12. 12. Document Planning <ul><li>Have a specific reader in mind – Always. </li></ul><ul><ul><li>The reader is intelligent but uninformed . </li></ul></ul><ul><ul><li>State the reader profile up front. </li></ul></ul><ul><ul><li>Example: </li></ul></ul><ul><ul><ul><li>Design Document for Command Line Parser </li></ul></ul></ul><ul><ul><ul><li>Reader Profile: </li></ul></ul></ul>Software Knowledge Relevance Domain Knowledge Reader Low Medium High Project Manager @ NFT High High Low Software Engineer @ Interra Low Medium Low Application Engineer @ HTL
    13. 13. Document Planning <ul><li>Decide what information to include. </li></ul><ul><ul><li>Frame of Reference: Objective </li></ul></ul><ul><ul><li>List Areas to Cover: </li></ul></ul>
    14. 14. Document Planning <ul><li>Decide what information to include. </li></ul><ul><ul><li>ToC: </li></ul></ul><ul><ul><ul><li>Command Mode </li></ul></ul></ul><ul><ul><ul><ul><li>Direct </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Indirect </li></ul></ul></ul></ul><ul><ul><ul><li>Architecture </li></ul></ul></ul><ul><ul><ul><li>Generic Command Parser </li></ul></ul></ul><ul><ul><ul><ul><li>Generic Command Structure </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Parsing Algorithm </li></ul></ul></ul></ul><ul><ul><ul><li>Application-Specific Command Parser </li></ul></ul></ul><ul><ul><ul><ul><li>Application-Specific Command Structure </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Instantiating Commands </li></ul></ul></ul></ul><ul><ul><ul><li>Error & Exception Handling </li></ul></ul></ul><ul><ul><ul><ul><li>Missing Command File </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Undefined Commands </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Illegal Command Parameters </li></ul></ul></ul></ul><ul><ul><ul><ul><li>Programming Exceptions </li></ul></ul></ul></ul><ul><ul><ul><li>Threaded Behavior </li></ul></ul></ul><ul><ul><ul><li>How to Test (Unit Tests) </li></ul></ul></ul><ul><ul><ul><li>References </li></ul></ul></ul>
    15. 15. Document Planning <ul><li>Identify Assistance </li></ul><ul><ul><li>Good Dictionary </li></ul></ul><ul><ul><li>Good Reviewer </li></ul></ul><ul><ul><li>. . . </li></ul></ul>
    16. 16. Language / Style Tips <ul><li>Avoid the following infractions: </li></ul><ul><ul><li>Typos & Spelling Errors (Spell-check). </li></ul></ul><ul><ul><li>Grammatical Errors (Grammar-check). </li></ul></ul><ul><ul><li>Use of passive voice (search for is, are, were, by, etc.); </li></ul></ul><ul><ul><ul><li>replace with the active voice </li></ul></ul></ul><ul><ul><li>Use of future tense (search for will); </li></ul></ul><ul><ul><ul><li>replace with the present tense </li></ul></ul></ul><ul><ul><li>Use of conditional tense (search for ould); </li></ul></ul><ul><ul><ul><li>replace with the present tense </li></ul></ul></ul>
    17. 17. Language / Style Tips <ul><li>Avoid the following infractions: </li></ul><ul><ul><li>Use of contractions (n’t and ’ve); </li></ul></ul><ul><ul><ul><li>replace with full words </li></ul></ul></ul><ul><ul><li>Use of non-parallel construction (bulleted lists); </li></ul></ul><ul><ul><ul><li>ensure that the first word of each list item is of the same type (noun, verb) </li></ul></ul></ul><ul><ul><li>Use of unclear antecedent (&quot;This&quot;); </li></ul></ul><ul><ul><ul><li>ensure that &quot;This&quot; is followed by a noun and not a verb </li></ul></ul></ul><ul><ul><li>Use of and/or; </li></ul></ul><ul><ul><ul><li>replace with &quot;. . . or . . ., or both&quot; </li></ul></ul></ul><ul><ul><li>Use of forbidden words </li></ul></ul><ul><ul><li>Broken links. </li></ul></ul>
    18. 18. 4 C’s of Technical Documentation <ul><li>Clarity </li></ul><ul><ul><li>Can it be easily understood by the audience? </li></ul></ul><ul><li>Comprehensiveness </li></ul><ul><ul><li>Is all of the necessary information present? </li></ul></ul><ul><li>Conciseness </li></ul><ul><ul><li>Is it clear without excess verbiage? </li></ul></ul><ul><li>Correctness </li></ul><ul><ul><li>Is grammatically correct? </li></ul></ul><ul><ul><li>Is it technically sound? </li></ul></ul><ul><ul><li>Does it follow conventions? </li></ul></ul>
    19. 19. References <ul><li>Articles in Interra TechPubs Site: </li></ul>
    20. 20. Credits / Acknowledgements <ul><li>Sabarni Guha </li></ul><ul><ul><li>For the first draft of this Presentation </li></ul></ul>
    21. 21. Thank You