| 1 | <?xml version="1.0" encoding="utf-8" ?> |
|---|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
|---|
| 4 | <head> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
|---|
| 6 | <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> |
|---|
| 7 | <meta name="version" content="S5 1.1" /> |
|---|
| 8 | <title>PYCon Tutorial</title> |
|---|
| 9 | <style type="text/css"> |
|---|
| 10 | |
|---|
| 11 | /* |
|---|
| 12 | :Author: David Goodger |
|---|
| 13 | :Contact: goodger@users.sourceforge.net |
|---|
| 14 | :Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $ |
|---|
| 15 | :Revision: $Revision: 4224 $ |
|---|
| 16 | :Copyright: This stylesheet has been placed in the public domain. |
|---|
| 17 | |
|---|
| 18 | Default cascading style sheet for the HTML output of Docutils. |
|---|
| 19 | |
|---|
| 20 | See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to |
|---|
| 21 | customize this style sheet. |
|---|
| 22 | */ |
|---|
| 23 | |
|---|
| 24 | /* used to remove borders from tables and images */ |
|---|
| 25 | .borderless, table.borderless td, table.borderless th { |
|---|
| 26 | border: 0 } |
|---|
| 27 | |
|---|
| 28 | table.borderless td, table.borderless th { |
|---|
| 29 | /* Override padding for "table.docutils td" with "! important". |
|---|
| 30 | The right padding separates the table cells. */ |
|---|
| 31 | padding: 0 0.5em 0 0 ! important } |
|---|
| 32 | |
|---|
| 33 | .first { |
|---|
| 34 | /* Override more specific margin styles with "! important". */ |
|---|
| 35 | margin-top: 0 ! important } |
|---|
| 36 | |
|---|
| 37 | .last, .with-subtitle { |
|---|
| 38 | margin-bottom: 0 ! important } |
|---|
| 39 | |
|---|
| 40 | .hidden { |
|---|
| 41 | display: none } |
|---|
| 42 | |
|---|
| 43 | a.toc-backref { |
|---|
| 44 | text-decoration: none ; |
|---|
| 45 | color: black } |
|---|
| 46 | |
|---|
| 47 | blockquote.epigraph { |
|---|
| 48 | margin: 2em 5em ; } |
|---|
| 49 | |
|---|
| 50 | dl.docutils dd { |
|---|
| 51 | margin-bottom: 0.5em } |
|---|
| 52 | |
|---|
| 53 | /* Uncomment (and remove this text!) to get bold-faced definition list terms |
|---|
| 54 | dl.docutils dt { |
|---|
| 55 | font-weight: bold } |
|---|
| 56 | */ |
|---|
| 57 | |
|---|
| 58 | div.abstract { |
|---|
| 59 | margin: 2em 5em } |
|---|
| 60 | |
|---|
| 61 | div.abstract p.topic-title { |
|---|
| 62 | font-weight: bold ; |
|---|
| 63 | text-align: center } |
|---|
| 64 | |
|---|
| 65 | div.admonition, div.attention, div.caution, div.danger, div.error, |
|---|
| 66 | div.hint, div.important, div.note, div.tip, div.warning { |
|---|
| 67 | margin: 2em ; |
|---|
| 68 | border: medium outset ; |
|---|
| 69 | padding: 1em } |
|---|
| 70 | |
|---|
| 71 | div.admonition p.admonition-title, div.hint p.admonition-title, |
|---|
| 72 | div.important p.admonition-title, div.note p.admonition-title, |
|---|
| 73 | div.tip p.admonition-title { |
|---|
| 74 | font-weight: bold ; |
|---|
| 75 | font-family: sans-serif } |
|---|
| 76 | |
|---|
| 77 | div.attention p.admonition-title, div.caution p.admonition-title, |
|---|
| 78 | div.danger p.admonition-title, div.error p.admonition-title, |
|---|
| 79 | div.warning p.admonition-title { |
|---|
| 80 | color: red ; |
|---|
| 81 | font-weight: bold ; |
|---|
| 82 | font-family: sans-serif } |
|---|
| 83 | |
|---|
| 84 | /* Uncomment (and remove this text!) to get reduced vertical space in |
|---|
| 85 | compound paragraphs. |
|---|
| 86 | div.compound .compound-first, div.compound .compound-middle { |
|---|
| 87 | margin-bottom: 0.5em } |
|---|
| 88 | |
|---|
| 89 | div.compound .compound-last, div.compound .compound-middle { |
|---|
| 90 | margin-top: 0.5em } |
|---|
| 91 | */ |
|---|
| 92 | |
|---|
| 93 | div.dedication { |
|---|
| 94 | margin: 2em 5em ; |
|---|
| 95 | text-align: center ; |
|---|
| 96 | font-style: italic } |
|---|
| 97 | |
|---|
| 98 | div.dedication p.topic-title { |
|---|
| 99 | font-weight: bold ; |
|---|
| 100 | font-style: normal } |
|---|
| 101 | |
|---|
| 102 | div.figure { |
|---|
| 103 | margin-left: 2em ; |
|---|
| 104 | margin-right: 2em } |
|---|
| 105 | |
|---|
| 106 | div.footer, div.header { |
|---|
| 107 | clear: both; |
|---|
| 108 | font-size: smaller } |
|---|
| 109 | |
|---|
| 110 | div.line-block { |
|---|
| 111 | display: block ; |
|---|
| 112 | margin-top: 1em ; |
|---|
| 113 | margin-bottom: 1em } |
|---|
| 114 | |
|---|
| 115 | div.line-block div.line-block { |
|---|
| 116 | margin-top: 0 ; |
|---|
| 117 | margin-bottom: 0 ; |
|---|
| 118 | margin-left: 1.5em } |
|---|
| 119 | |
|---|
| 120 | div.sidebar { |
|---|
| 121 | margin-left: 1em ; |
|---|
| 122 | border: medium outset ; |
|---|
| 123 | padding: 1em ; |
|---|
| 124 | background-color: #ffffee ; |
|---|
| 125 | width: 40% ; |
|---|
| 126 | float: right ; |
|---|
| 127 | clear: right } |
|---|
| 128 | |
|---|
| 129 | div.sidebar p.rubric { |
|---|
| 130 | font-family: sans-serif ; |
|---|
| 131 | font-size: medium } |
|---|
| 132 | |
|---|
| 133 | div.system-messages { |
|---|
| 134 | margin: 5em } |
|---|
| 135 | |
|---|
| 136 | div.system-messages h1 { |
|---|
| 137 | color: red } |
|---|
| 138 | |
|---|
| 139 | div.system-message { |
|---|
| 140 | border: medium outset ; |
|---|
| 141 | padding: 1em } |
|---|
| 142 | |
|---|
| 143 | div.system-message p.system-message-title { |
|---|
| 144 | color: red ; |
|---|
| 145 | font-weight: bold } |
|---|
| 146 | |
|---|
| 147 | div.topic { |
|---|
| 148 | margin: 2em } |
|---|
| 149 | |
|---|
| 150 | h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, |
|---|
| 151 | h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { |
|---|
| 152 | margin-top: 0.4em } |
|---|
| 153 | |
|---|
| 154 | h1.title { |
|---|
| 155 | text-align: center } |
|---|
| 156 | |
|---|
| 157 | h2.subtitle { |
|---|
| 158 | text-align: center } |
|---|
| 159 | |
|---|
| 160 | hr.docutils { |
|---|
| 161 | width: 75% } |
|---|
| 162 | |
|---|
| 163 | img.align-left { |
|---|
| 164 | clear: left } |
|---|
| 165 | |
|---|
| 166 | img.align-right { |
|---|
| 167 | clear: right } |
|---|
| 168 | |
|---|
| 169 | ol.simple, ul.simple { |
|---|
| 170 | margin-bottom: 1em } |
|---|
| 171 | |
|---|
| 172 | ol.arabic { |
|---|
| 173 | list-style: decimal } |
|---|
| 174 | |
|---|
| 175 | ol.loweralpha { |
|---|
| 176 | list-style: lower-alpha } |
|---|
| 177 | |
|---|
| 178 | ol.upperalpha { |
|---|
| 179 | list-style: upper-alpha } |
|---|
| 180 | |
|---|
| 181 | ol.lowerroman { |
|---|
| 182 | list-style: lower-roman } |
|---|
| 183 | |
|---|
| 184 | ol.upperroman { |
|---|
| 185 | list-style: upper-roman } |
|---|
| 186 | |
|---|
| 187 | p.attribution { |
|---|
| 188 | text-align: right ; |
|---|
| 189 | margin-left: 50% } |
|---|
| 190 | |
|---|
| 191 | p.caption { |
|---|
| 192 | font-style: italic } |
|---|
| 193 | |
|---|
| 194 | p.credits { |
|---|
| 195 | font-style: italic ; |
|---|
| 196 | font-size: smaller } |
|---|
| 197 | |
|---|
| 198 | p.label { |
|---|
| 199 | white-space: nowrap } |
|---|
| 200 | |
|---|
| 201 | p.rubric { |
|---|
| 202 | font-weight: bold ; |
|---|
| 203 | font-size: larger ; |
|---|
| 204 | color: maroon ; |
|---|
| 205 | text-align: center } |
|---|
| 206 | |
|---|
| 207 | p.sidebar-title { |
|---|
| 208 | font-family: sans-serif ; |
|---|
| 209 | font-weight: bold ; |
|---|
| 210 | font-size: larger } |
|---|
| 211 | |
|---|
| 212 | p.sidebar-subtitle { |
|---|
| 213 | font-family: sans-serif ; |
|---|
| 214 | font-weight: bold } |
|---|
| 215 | |
|---|
| 216 | p.topic-title { |
|---|
| 217 | font-weight: bold } |
|---|
| 218 | |
|---|
| 219 | pre.address { |
|---|
| 220 | margin-bottom: 0 ; |
|---|
| 221 | margin-top: 0 ; |
|---|
| 222 | font-family: serif ; |
|---|
| 223 | font-size: 100% } |
|---|
| 224 | |
|---|
| 225 | pre.literal-block, pre.doctest-block { |
|---|
| 226 | margin-left: 2em ; |
|---|
| 227 | margin-right: 2em ; |
|---|
| 228 | background-color: #eeeeee } |
|---|
| 229 | |
|---|
| 230 | span.classifier { |
|---|
| 231 | font-family: sans-serif ; |
|---|
| 232 | font-style: oblique } |
|---|
| 233 | |
|---|
| 234 | span.classifier-delimiter { |
|---|
| 235 | font-family: sans-serif ; |
|---|
| 236 | font-weight: bold } |
|---|
| 237 | |
|---|
| 238 | span.interpreted { |
|---|
| 239 | font-family: sans-serif } |
|---|
| 240 | |
|---|
| 241 | span.option { |
|---|
| 242 | white-space: nowrap } |
|---|
| 243 | |
|---|
| 244 | span.pre { |
|---|
| 245 | white-space: pre } |
|---|
| 246 | |
|---|
| 247 | span.problematic { |
|---|
| 248 | color: red } |
|---|
| 249 | |
|---|
| 250 | span.section-subtitle { |
|---|
| 251 | /* font-size relative to parent (h1..h6 element) */ |
|---|
| 252 | font-size: 80% } |
|---|
| 253 | |
|---|
| 254 | table.citation { |
|---|
| 255 | border-left: solid 1px gray; |
|---|
| 256 | margin-left: 1px } |
|---|
| 257 | |
|---|
| 258 | table.docinfo { |
|---|
| 259 | margin: 2em 4em } |
|---|
| 260 | |
|---|
| 261 | table.docutils { |
|---|
| 262 | margin-top: 0.5em ; |
|---|
| 263 | margin-bottom: 0.5em } |
|---|
| 264 | |
|---|
| 265 | table.footnote { |
|---|
| 266 | border-left: solid 1px black; |
|---|
| 267 | margin-left: 1px } |
|---|
| 268 | |
|---|
| 269 | table.docutils td, table.docutils th, |
|---|
| 270 | table.docinfo td, table.docinfo th { |
|---|
| 271 | padding-left: 0.5em ; |
|---|
| 272 | padding-right: 0.5em ; |
|---|
| 273 | vertical-align: top } |
|---|
| 274 | |
|---|
| 275 | table.docutils th.field-name, table.docinfo th.docinfo-name { |
|---|
| 276 | font-weight: bold ; |
|---|
| 277 | text-align: left ; |
|---|
| 278 | white-space: nowrap ; |
|---|
| 279 | padding-left: 0 } |
|---|
| 280 | |
|---|
| 281 | h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, |
|---|
| 282 | h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { |
|---|
| 283 | font-size: 100% } |
|---|
| 284 | |
|---|
| 285 | tt.docutils { |
|---|
| 286 | background-color: #eeeeee } |
|---|
| 287 | |
|---|
| 288 | ul.auto-toc { |
|---|
| 289 | list-style-type: none } |
|---|
| 290 | |
|---|
| 291 | </style> |
|---|
| 292 | <!-- configuration parameters --> |
|---|
| 293 | <meta name="defaultView" content="slideshow" /> |
|---|
| 294 | <meta name="controlVis" content="hidden" /> |
|---|
| 295 | <!-- style sheet links --> |
|---|
| 296 | <script src="ui/default/slides.js" type="text/javascript"></script> |
|---|
| 297 | <link rel="stylesheet" href="ui/default/slides.css" |
|---|
| 298 | type="text/css" media="projection" id="slideProj" /> |
|---|
| 299 | <link rel="stylesheet" href="ui/default/outline.css" |
|---|
| 300 | type="text/css" media="screen" id="outlineStyle" /> |
|---|
| 301 | <link rel="stylesheet" href="ui/default/print.css" |
|---|
| 302 | type="text/css" media="print" id="slidePrint" /> |
|---|
| 303 | <link rel="stylesheet" href="ui/default/opera.css" |
|---|
| 304 | type="text/css" media="projection" id="operaFix" /> |
|---|
| 305 | |
|---|
| 306 | <style type="text/css"> |
|---|
| 307 | #currentSlide {display: none;} |
|---|
| 308 | </style> |
|---|
| 309 | </head> |
|---|
| 310 | <body> |
|---|
| 311 | <div class="layout"> |
|---|
| 312 | <div id="controls"></div> |
|---|
| 313 | <div id="currentSlide"></div> |
|---|
| 314 | <div id="header"> |
|---|
| 315 | |
|---|
| 316 | </div> |
|---|
| 317 | <div id="footer"> |
|---|
| 318 | <h1>PYCon Tutorial</h1> |
|---|
| 319 | |
|---|
| 320 | </div> |
|---|
| 321 | </div> |
|---|
| 322 | <div class="presentation"> |
|---|
| 323 | <div class="slide" id="slide0"> |
|---|
| 324 | <h1 class="title">PYCon Tutorial</h1> |
|---|
| 325 | <p>How to document an open source Project ?</p> |
|---|
| 326 | <p><<a class="reference" href="mailto:tarek@ziade.org">tarek@ziade.org</a>></p> |
|---|
| 327 | <!-- contents: --> |
|---|
| 328 | |
|---|
| 329 | </div> |
|---|
| 330 | <div class="slide" id="how-am-i"> |
|---|
| 331 | <h1>How am I ?</h1> |
|---|
| 332 | <ul class="simple"> |
|---|
| 333 | <li>Python developer since 2000</li> |
|---|
| 334 | <li>Core developer in Nuxeo CPS (Zope) for 3 years</li> |
|---|
| 335 | <li>Involved in Zope sprints</li> |
|---|
| 336 | <li>Author of a french book "Programmation Python" (Eyrolles, 2006)</li> |
|---|
| 337 | <li>Creator of AFPY (french speaking PUG)</li> |
|---|
| 338 | <li>CTO at Emencia, for a Python e-commerce framework</li> |
|---|
| 339 | </ul> |
|---|
| 340 | </div> |
|---|
| 341 | <div class="slide" id="what-are-the-goals-of-this-tutorial"> |
|---|
| 342 | <h1>What are the goals of this tutorial ?</h1> |
|---|
| 343 | <ul class="simple"> |
|---|
| 344 | <li>Understand the place of documentation in software projects</li> |
|---|
| 345 | <li>Learn a few patterns to document your project</li> |
|---|
| 346 | <li>Practice them !</li> |
|---|
| 347 | </ul> |
|---|
| 348 | </div> |
|---|
| 349 | <div class="slide" id="how-this-tutorial-is-organized"> |
|---|
| 350 | <h1>How this tutorial is organized ?</h1> |
|---|
| 351 | <ul class="simple"> |
|---|
| 352 | <li>Each part comes with:</li> |
|---|
| 353 | </ul> |
|---|
| 354 | <blockquote> |
|---|
| 355 | <ul class="simple"> |
|---|
| 356 | <li>a few slides</li> |
|---|
| 357 | <li>exercises <em>you</em> do.</li> |
|---|
| 358 | </ul> |
|---|
| 359 | </blockquote> |
|---|
| 360 | </div> |
|---|
| 361 | <div class="slide" id="the-plan"> |
|---|
| 362 | <h1>The plan</h1> |
|---|
| 363 | <ul class="simple"> |
|---|
| 364 | <li>A few definitions</li> |
|---|
| 365 | <li>Part 1: Writing a document</li> |
|---|
| 366 | <li>Part 2: Writing documents for Python</li> |
|---|
| 367 | <li>BREAK - Yepeee</li> |
|---|
| 368 | <li>Part 3: Using documents for TDD</li> |
|---|
| 369 | <li>Part 4: Writing documents for a Python project</li> |
|---|
| 370 | <li>LUNCH - Yeeahhaa</li> |
|---|
| 371 | </ul> |
|---|
| 372 | </div> |
|---|
| 373 | <div class="slide" id="a-few-definitions"> |
|---|
| 374 | <h1>A few definitions</h1> |
|---|
| 375 | <p>What kind of documentation are we talking about ?</p> |
|---|
| 376 | </div> |
|---|
| 377 | <div class="slide" id="id1"> |
|---|
| 378 | <h1>A few definitions</h1> |
|---|
| 379 | <p>Technical documentation that helps to understand how a codebase |
|---|
| 380 | works and how it can be used.</p> |
|---|
| 381 | <p>This can be:</p> |
|---|
| 382 | <ul class="simple"> |
|---|
| 383 | <li>a document describing a package, a module or a serie of package</li> |
|---|
| 384 | <li>a glossary</li> |
|---|
| 385 | <li>a tutorial</li> |
|---|
| 386 | <li>a recipe</li> |
|---|
| 387 | </ul> |
|---|
| 388 | </div> |
|---|
| 389 | <div class="slide" id="id2"> |
|---|
| 390 | <h1>A few definitions</h1> |
|---|
| 391 | <p>What is the use and who is the target ?</p> |
|---|
| 392 | </div> |
|---|
| 393 | <div class="slide" id="id3"> |
|---|
| 394 | <h1>A few definitions</h1> |
|---|
| 395 | <ul class="simple"> |
|---|
| 396 | <li>Project developers, to...<ul> |
|---|
| 397 | <li>build a shared knowledge</li> |
|---|
| 398 | <li>improve code quality</li> |
|---|
| 399 | </ul> |
|---|
| 400 | </li> |
|---|
| 401 | <li>Community, to...<ul> |
|---|
| 402 | <li>facilitate participation (e.g. non developers)</li> |
|---|
| 403 | <li>facilitate adoption and comprehension</li> |
|---|
| 404 | </ul> |
|---|
| 405 | </li> |
|---|
| 406 | </ul> |
|---|
| 407 | </div> |
|---|
| 408 | <div class="slide" id="part-1"> |
|---|
| 409 | <h1>Part 1</h1> |
|---|
| 410 | <p>Part 1 - Writing a document</p> |
|---|
| 411 | <p>This part is composed of three sections:</p> |
|---|
| 412 | <ul class="simple"> |
|---|
| 413 | <li>Mastering reStructuredText</li> |
|---|
| 414 | <li>Writing techniques ans tips: the seven laws</li> |
|---|
| 415 | <li>Team writing</li> |
|---|
| 416 | </ul> |
|---|
| 417 | </div> |
|---|
| 418 | <div class="slide" id="mastering-restructuredtext"> |
|---|
| 419 | <h1>Mastering reSTructuredText</h1> |
|---|
| 420 | <p>reSTructuredText is</p> |
|---|
| 421 | <ul class="simple"> |
|---|
| 422 | <li>a plaintext markup syntax and parser system</li> |
|---|
| 423 | <li>easy to read as-is, yet powerful</li> |
|---|
| 424 | <li>the Pythonistas laTeX</li> |
|---|
| 425 | </ul> |
|---|
| 426 | </div> |
|---|
| 427 | <div class="slide" id="id4"> |
|---|
| 428 | <h1>Mastering reSTructuredText</h1> |
|---|
| 429 | <ul class="simple"> |
|---|
| 430 | <li>example (Tarek, switch on)</li> |
|---|
| 431 | <li>cheatsheet</li> |
|---|
| 432 | <li>see <a class="reference" href="http://docutils.sf.net">http://docutils.sf.net</a></li> |
|---|
| 433 | </ul> |
|---|
| 434 | </div> |
|---|
| 435 | <div class="slide" id="id5"> |
|---|
| 436 | <h1>Mastering reSTructuredText</h1> |
|---|
| 437 | <p><img alt="smile" src="media/smile.png" /> let's do exercise #1 and #2</p> |
|---|
| 438 | </div> |
|---|
| 439 | <div class="slide" id="id6"> |
|---|
| 440 | <h1>Mastering reSTructuredText</h1> |
|---|
| 441 | <p>reST can be:</p> |
|---|
| 442 | <ul class="simple"> |
|---|
| 443 | <li>used for all documentation needs</li> |
|---|
| 444 | <li>manipulated like code (versioning, etc.)</li> |
|---|
| 445 | <li>easily transformed into various shapes</li> |
|---|
| 446 | </ul> |
|---|
| 447 | <p>Python developers <img alt="love" src="media/love.png" /> reST</p> |
|---|
| 448 | </div> |
|---|
| 449 | <div class="slide" id="writing-techniques-and-tips"> |
|---|
| 450 | <h1>Writing techniques and tips</h1> |
|---|
| 451 | <p>The seven <em>laws</em> for technical writing:</p> |
|---|
| 452 | <ul class="simple"> |
|---|
| 453 | <li>Two-step writing process</li> |
|---|
| 454 | <li>Simple style</li> |
|---|
| 455 | <li>Targeted readership</li> |
|---|
| 456 | <li>Focused information</li> |
|---|
| 457 | <li>Realistic examples</li> |
|---|
| 458 | <li>"Light but sufficient" approach</li> |
|---|
| 459 | <li>Structured documents</li> |
|---|
| 460 | </ul> |
|---|
| 461 | </div> |
|---|
| 462 | <div class="slide" id="the-two-step-writing-process"> |
|---|
| 463 | <h1>The Two-step writing process</h1> |
|---|
| 464 | <p>Writing should be done in two stages (Elbow, 1980):</p> |
|---|
| 465 | <ul class="simple"> |
|---|
| 466 | <li>a free writing where ideas are written on the paper no matter the shape.</li> |
|---|
| 467 | <li>a review stage where things are structured and reviewed.</li> |
|---|
| 468 | </ul> |
|---|
| 469 | <p>Each stage should take 50% of the time.</p> |
|---|
| 470 | <p><img alt="important" src="media/important.png" /> Split you writing time in two phases, no one can write it right |
|---|
| 471 | the first time (except Mozart)</p> |
|---|
| 472 | </div> |
|---|
| 473 | <div class="slide" id="simple-style"> |
|---|
| 474 | <h1>Simple style</h1> |
|---|
| 475 | <ul class="simple"> |
|---|
| 476 | <li>Use short sentences and simple writing style.</li> |
|---|
| 477 | <li>Use simple vocabulary</li> |
|---|
| 478 | </ul> |
|---|
| 479 | </div> |
|---|
| 480 | <div class="slide" id="targeted-readership"> |
|---|
| 481 | <h1>Targeted readership</h1> |
|---|
| 482 | <p>Focus on your target when you write a document (RÃŒping, 2003).</p> |
|---|
| 483 | <p>Assume their background knowledge to restrict the scope of the documentation.</p> |
|---|
| 484 | <p><img alt="important" src="media/important.png" /> A <em>prerequest</em> section can help a lot.</p> |
|---|
| 485 | </div> |
|---|
| 486 | <div class="slide" id="focused-information"> |
|---|
| 487 | <h1>Focused information</h1> |
|---|
| 488 | <p>A document is about a clear focus.</p> |
|---|
| 489 | <p>A precise title for each section and the document itself, and a summary |
|---|
| 490 | can help.</p> |
|---|
| 491 | <p><img alt="important" src="media/important.png" /> If you cannot easily name the document or one of its section, |
|---|
| 492 | there's a problem</p> |
|---|
| 493 | </div> |
|---|
| 494 | <div class="slide" id="realistic-examples"> |
|---|
| 495 | <h1>Realistic examples</h1> |
|---|
| 496 | <p>Drop the <em>foo</em> and <em>bar</em> habits. Examples must be real-life examples:</p> |
|---|
| 497 | <p>Neh:</p> |
|---|
| 498 | <pre class="literal-block"> |
|---|
| 499 | >>> from package import graph |
|---|
| 500 | >>> foo = graph.calculateSquare(1, 1, 1, 1) |
|---|
| 501 | >>> bar = graph.renderSquare(foo) |
|---|
| 502 | </pre> |
|---|
| 503 | <p>Better:</p> |
|---|
| 504 | <pre class="literal-block"> |
|---|
| 505 | >>> from package import graph |
|---|
| 506 | >>> square = graph.calculateSquare(1, 7, 1, 10) |
|---|
| 507 | >>> square_view = graph.renderSquare(square) |
|---|
| 508 | </pre> |
|---|
| 509 | </div> |
|---|
| 510 | <div class="slide" id="light-but-sufficient-approach"> |
|---|
| 511 | <h1>"Light but sufficient" approach</h1> |
|---|
| 512 | <p>A working software is more important than the best documentation in the world |
|---|
| 513 | (Ambler, 2002).</p> |
|---|
| 514 | <p><em>Quality over Quantity</em> is the best rule.</p> |
|---|
| 515 | <p><img alt="important" src="media/important.png" /> Spending too much time to find something in the documentation is |
|---|
| 516 | a bad sign.</p> |
|---|
| 517 | <p><img alt="important" src="media/important.png" /> Think documents like code. Always limit the size of its sections, |
|---|
| 518 | examples, etc.</p> |
|---|
| 519 | <p><img alt="wink" src="media/wink.png" /> Modularized documentation is the key.</p> |
|---|
| 520 | </div> |
|---|
| 521 | <div class="slide" id="structured-documents"> |
|---|
| 522 | <h1>Structured documents</h1> |
|---|
| 523 | <p>Use a clear document portfolio to facilitate the reading. Document should |
|---|
| 524 | use:</p> |
|---|
| 525 | <ul class="simple"> |
|---|
| 526 | <li>an abstract with a readers guideline</li> |
|---|
| 527 | <li>a toc when there are more than one section</li> |
|---|
| 528 | <li>references</li> |
|---|
| 529 | <li>glossary</li> |
|---|
| 530 | <li>tables and diagrams</li> |
|---|
| 531 | </ul> |
|---|
| 532 | <p><img alt="important" src="media/important.png" /> Never write a document that doesn't have a template</p> |
|---|
| 533 | </div> |
|---|
| 534 | <div class="slide" id="id7"> |
|---|
| 535 | <h1>Writing techniques and tips</h1> |
|---|
| 536 | <p>Distribution of tipsheet, let's do exercise #3, and apply the laws <img alt="smile" src="media/smile.png" /></p> |
|---|
| 537 | </div> |
|---|
| 538 | <div class="slide" id="team-writing"> |
|---|
| 539 | <h1>Team writing |
|---|
