Uploaded byMichael Marotta
Documentation for developers
The document is a presentation on effective documentation practices by Michael E. Marotta, emphasizing the importance of thorough planning and clear writing in technical documentation. It outlines principles, tools, and common pitfalls in writing, advocating for readability and proper documentation standards. Marotta draws on personal experiences and various resources to provide guidelines for creating impactful user manuals and technical documents.
More Related Content
Similar to Documentation for developers
Documentation for developers
- 1. Documentation for Developers by Michael E. Marotta mike49mercury@gmail.com Presentedto “Austin on Rails” May 28, 2013
- 2. As a contractor,I have worked for many companies, on many platforms over the years. I wrote my first user manual for Oldsmobile in January 1984. What I bring to you came from insight, learning, correcting mistakes, testing theories, and developing a consistent and proven set of guidelines for success.
- 3. Rule #1 These toolswork if you use them.
- 4. Rule #0 To doit right, you must love the doing. This is from The Fountainhead by Ayn Rand. “To do things for other people, you must be the kind of man who can get things done. But to get things done, you must love the doing.” (If you do not love writing documentation, find someone who does.)
- 5. Definition Luck is the combinationof hard work and planning. This is usually attributed to the Marine Corps. You cannot just throw it together and hope for the best.
- 6. Axiom: Documentation is specification. We willsee that the way to begin the process is to create the final output first. To create a complex software system and then call in the technical writer is to build a house without plans and then call in a drafter.
- 7. Successful pilots spendas much or more time planning the flight than being in the air. The most popular store for private pilots sells 153 different flight planning tools. Jeppesen for commercial pilots has about the same depth of offerings.
- 8. In 1976, JosephWeizenbaum of the MIT Artificial Intelligence Lab compared programmers to gamblers.
- 9. Like superstitious gamblers,programmers believe that one more patch, one more fix will solve their problems. But their problems began with their lack of understanding of the substantive literature of their field, whether it be crystallography, or retail sales.
- 10. “You could makea pretty good word processor with this.” -- Geoff Rarick The tools presented here are variously adaptable. Use them as you can.
- 11. the only “don’t” theonly “thou shalt not” Do not design in code.
- 12.
- 13.
- 14. Basic Flowchart Cause andEffect Diagram Cross Functional Flowchart Visio Business Processes
- 15.
- 16. A conclusion isthe place at which you stopped thinking. The best way to learn something is to teach it to someone else.
- 17.
- 18.
- 20.
- 21.
- 22.
- 24. GOOD WRITING • SHORT,DECLARATIVE SENTENCES • ACTIVE VOICE • PRESENT TENSE • THIRD PERSON (OR SECOND, AS NEEDED) • INDICATIVE MOOD
- 25. READABILITY is the onlymeasure. … and what you can measure, you can improve. The examples here show the metrics of readability provided by Microsoft Word.
- 26. The Sermon onthe Mount Fifth grade reading level.
- 27. The Declaration ofIndependence Grade 18 reading level: high school plus 6 years.
- 28.
- 29. Grade 10.4 Peer-reviewed journalarticle for the British Association for the History of Astronomy. Technical writing can be easy to read.
- 30. IT Hardware DisposalPolicy Reading level 12.9 100% passive voice. Almost college level. Will these policies be followed?
- 31. IT Hardware DisposalPolicy Reading level 12.9 I marked up the problems. Then, I fixed them.
- 32. One grade levellower. Active voice.
- 33. Millington’s Rule If youare following the manual, then you are not using the current version. Bush ploy foxes pundits. Languages change over time. English is a global language. Your local vernacular may not be understood even by everyone in your office.
- 34.
- 35. So, I wentto Ruby repositories, looking for examples of bad documentation. I was willing to spend an hour or more, drilling down, and digging deep to come up with egregious examples. It was not that hard. The problems were not “egregious” only common, many, and easy to fix or avoid.
- 36. Of course, Iwas interested in “readability.” A Ruby method to measure it would be a valuable addition to my own box of tools.
- 37.
- 38. “Extractor” The program shouldbe called “Extractor” because it does not measure readability. Rather, it gathers the text from a webpage, based on the tags around the text.
- 39. Rdoc versus Weizenbaum TheMS-Word Grammar Checker is not the only standard. The example below reads at an 11.8 level. That could be improved, of course. Among real problems are the assumption of previous knowledge and the meaningless phrases. At root, the program simply does not do what it implicitly claims. Rdoc is not a code parser that creates documentation. Rather, the program reads the source code, identifies comment tags, and reformats the comments into HTML presentation. If the comments are meaningless or missing entirely, Rdoc does nothing for you. And the documentation has a bug: an unclosed parenthesis.
- 40. Rdoc versus Weizenbaum http://rdoc.sourceforge.net/ http://rdoc.sourceforge.net/doc/files/rdoc/parsers/parse_c_rb.html •Rdoc is an application that produces documentation for one or more Ruby source files. We work similarly to JavaDoc, parsing the source, and extracting the definition for classes, modules, and methods (along with includes and requires). We associate with these optional documentation contained in the immediately preceding comment block, and then render the result using a pluggable output formatter. (Currently, HTML is the only supported format. Markup is a library that converts plain text into various output formats. The Markup library is used to interpret the comment blocks that Rdoc uses to document methods, classes, and so on.
- 41. See Sally work. Sallyplans her work. Run, Sally, run.
- 42. Sallie Mae The studentloan company delivers excellent online support. Prompts are clear and correct. I never found a bug. When you hover over a field, the pop-up tells you what you need to know. Three examples follow.
- 46.
- 47. Contact Information • mike49mercury@gmail.com •NecessaryFacts.blogspot.com The End
Editor's Notes
- #2 Presented to “Austin on Rails” May 28 2013, 7:00 PM at The Capital Factory.
- #3 I started as a computer programmer. On a database project for General Motors, no one wanted to write the user manual. I had written two small books and published half a dozen magazine articles, so I wrote it. Over the years, I did more documentation and less programming. In the 1980s and 1990s, I used the TeX/LaTeX typesetting language. TeX was the antecedent to SGML from which came HTML.
- #4 The best documentation creates an organic system of knowledge.
- #5 If you do not love writing documentation, then find someone who does. The quote is from The Fountainhead by Ayn Rand. Peter Keating would like to design a large government housing, but he never developed the skill. He was always a “people person.” He has come to Howard Roark for help – as he did several times since their college days. Roark considers clients to be like steel and rock: part of the technical challenge. Roark understands Keating’s desire to help others – though he does not share it as a primary motive. Roark says, “to do things for other people, you need to be the kind of man who can get things done. But to get things done, Peter, you must love the doing.”
- #6 Usually attributed to the United States Marine Corps. We all work hard. The critical difference is the planning.
- #7 My own rule. Every project begins with some kind of documentation. The best projects begin with a full set of specifications. Those must include the user manuals. The user manuals define the goal. If you do not know where you are going, you never will arrive. Most often, technical specifications alone – perhaps only a statement of work – guide programmers who work intuitively. At the end of the process, they call in a technical writer to document their work. At that point, it is too late. Documenting “as built” work is like drawing blueprints for a house – or a neighborhood – after carpenters have been working as they pleased to do thei best job they know how according to their own best jjudgment. We can hope that they knew their crafts and got along well.
- #8 What if computing were as consequential as flying? We call aircraft “forgiving”. What if a bug resulted in an explosion and injuryto the programmer? Pilots spend as much time in flight planning as they do in flight, often more. To love flying, you must love the planning. Sporty’s Pilot Shop sells 153 different flight planning aids, from tablets of printed sheets to software to handheld dedicated computers. Jeppesen also serves private pilots but is favored by transport and passenger airline professionals Flight planning starts the documentation. At the end of your flight, professionals and advanced private pilots formally “close the plan” with the controllers.
- #9 Weizenbaum said that like gamblers, programmers have superstitions. Perhaps primary is the superstition that one more fix, one more patch will solve their problem. Weizebaum said that the real problem is that they begin writing programs without any knowledge of the substantive field in which they are working. He meant not the programming language or computer system, but the application, the supposed goal.
- #10 ... bright young men of disheveled appearance, often with sunken glowing eyes, can be seen sitting at computer consoles, their arms tensed and waiting to fire their fingers, already poised to strike, at the buttons and keys on which their attention seems to be riveted as a gambler's on the rolling dice. When not so transfixed, they often sit at tables strewn with computer printouts over which they pore like possessed students of a cabbalistic text. They work until they nearly drop, twenty, thirty hours at a time. Their food, if they arrange it, is brought to them: coffee, Cokes, sandwiches. If possible, they sleep on cots near the printouts. Their rumpled clothes, their unwashed and unshaven faces, and their uncombed hair all testify that they are oblivious to their bodies and to the world in which they move. These are computer bums, compulsive programmers…Joseph Weizenbaum, Computer Power and Human Reason: From Judgment to Calculation (W. H. Freeman, 1976) quoted in Hackers: Heroes of the Computer Revolution by Steven Levy. (Nerraw Manijaime/Doubleday, 1984).
- #11 Alan Turing showed that any finite state machine can model any other. Therefore, it matters not so much perhaps which tools you use, but that you have some methodology and some means of following it. The tools suggested here below all work about the same. But to work at all, you have to actually use them.
- #12 These tools work. You do not begin the design of a house with a little house or a replica made of different materials. Such modeling is important. Roller coasters are tested at one-third scale. But they do not begin that way. I know a local web designer who carries a box of Crayola Crayons. Architects do model in clay. Automobile designers do model in clay and wood. But they do not model a car by building one without any plan. You need a plan.
- #16 See “The Entity-Relationship Model: Toward a Unified View of Data” by Peter Pin-Shan Chen, MIT, ACM Transactions on Database Systems, vol 1 no 1. March 1976, pp 9-36.
- #17 The best way to learn something is to teach it to others. If you can explain your work, you will understand it better. If you cannot, then perhaps you need to do more thinking, collecting data, talking to users and experts, and otherwise planning your work.
- #18 http://en.wikipedia.org/wiki/Warnier/Orr_diagram: “Warnier/Orr diagram” See also http://www.mindapp.com/warnier-orr-basics/
- #19 Warnier-Orr does allow conditional branching and other controls. However, it is designed for large databases. For processes, other tools work better.
- #20 You can build the { signs yourself, or you can buy a package. This is just one out of many. They do offer a free demo download.
- #21 See “Flowchart Techniques for Structured Programming” by I. Nassi and B. Shneiderman, SUNY Stony Brook, SIGPLAN Notices, 1973 August. See also “ A short history of structured flowcharts (Nassi-Shneiderman Diagrams)” by Ben Shneiderman (Draft May 27, 2003) at http://www.cs.umd.edu/hcil/members/bshneiderman/nsd/ You can draw them for yourself and make them into macros. As shown below, firms that sell flowcharting software also sell Nass-Shneiderman diagrams.
- #23 And see, of course, http://en.wikipedia.org/wiki/Nassi%E2%80%93Shneiderman_diagram
- #24 E pluribus unum: One out of many. Just one out of many sellers.
- #25 Good technical writing is just good writing. Good technical writing is also easy to translate. I often recommend THE ELEMENTS OF STYLE by Strunk and White. It can be a bit dated, as it was addressed to a college audience in the 1920s, but the fundamental truths still apply (as time goes by). Active voice: She opens the door . versus Passive voice: The door is opened by her. Indicative mood: This will be good. versus Conditional mood: This would be good. Active voice shows who is responsible. Passive voice leaves questions : “The file is updated. ” Who updates the file? How is it updated? By what means?
- #27 From http://www.biblegateway.com/passage/?search=Matthew+5-7&version=NIV Matthew 5-7 New International Version (NIV).
- #28 Note that this passage actually has fewer passive voice sentences than the Sermon on the Mount. However, its long sentences- 53 words per sentence - render it difficult to grasp.
- #29 This was published for numismatists (“coin collectors”) who have leisure and a desire to enjoy literature about their hobby, avocation, or profession. It is an easy read.
- #30 This was published by the British Association for the History of Astronomy. It is an academic work that was peer-reviewed. It reads slightly easier than the article for coin collectors.
- #31 This was from an actual user manual for a recent project with good metrics, sensible design, and good oversight. I just wanted to use it as a positive example. So, I was surprised to see how poorly it scored. A closer read revealed why.
- #32 I marked up the problems; and then fixed them.
- #33 I lowered the reading level almost a full year grade, from 12.9 to 12.0. It still could be improved. Sometimes, however, you have to settle for good enough. In this case, as in much technical work, the sentences are necessarily long.
- #34 Language changes. However, it does not change uniformly over place. Your idea of common English may not be common. If you stick tho the manual, you might not be using the current version, but you will be more broadly understood.
- #35 You must invent a system of meaningful names. Cute names are not helpful. Abstract names are useless. If you want to learn something well, teach it to someone else. In other words, can you explain your intention? If not, then your goal may not be clear. Therefore, create comments that explain your intentions, goals, methods, means, suppositions, assumptions, conclusions, etc., etc. Originally, this came to me as a cartoon of two hardhats arguing in a bar. “Dammit! You need comments,” said the one to the other. That was from a programmer I worked with, Scott Waller.
- #36 So, I went looking for example of bad documentation in Ruby code. It was pretty easy to find.
- #37 Of course, I am interested in readability. This held promise for real use. I just did not understand what he meant by “extracting the primary readable content of a webpage.”
- #38 The Description should say something different from the Summary.
- #39 After reading the documentation, I felt that the program was misnamed. It does not measure readability at all. It extracts content.
- #44 Having been a customer of Sallie Mae since 2007, I never found anything to complain about on their website. They put a lot of care into their work.
- #45 Too often, when registering for a website, you do not get a message like this until after it rejects your password. Sallie Mae does it right.
- #46 Another good example
- #47 The End … Recap …