![Agenda ,[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]](data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7)
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Viewers also liked (20)
Similar to Technical Documentation By Techies
Similar to Technical Documentation By Techies (20)
More from ppd1961
More from ppd1961 (20)
Recently uploaded
Recently uploaded (20)
Technical Documentation By Techies
- 1. March 12, 2008 Technical Documentation by Techies Dr. Partha Pratim Das Interra Systems (India) Pvt. Ltd.
- 21. Thank You
Editor's Notes
- 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