Changeset 78:b5dabe9762d1 for PyCon07/slides.txt
- Timestamp:
- 04/12/07 17:38:04 (17 months ago)
- Files:
-
- 1 modified
-
PyCon07/slides.txt (modified) (24 diffs)
Legend:
- Unmodified
- Added
- Removed
-
PyCon07/slides.txt
r76 r78 22 22 - Creator of AFPY (french speaking PUG) 23 23 24 - CTO at Emencia, for a Python e-commerce framework 24 - CTO at Emencia, for a Python e-commerce framework 25 25 26 26 … … 30 30 - Understand the place of documentation in software projects 31 31 32 - Learn a few patterns to document your project 32 - Learn a few patterns to document your project 33 33 34 34 - Practice them ! … … 38 38 39 39 - Each part comes with: 40 40 41 41 - a few slides 42 42 - exercises *you* do. … … 53 53 - LUNCH - Yeeahhaa 54 54 55 A few definitions 55 A few definitions 56 56 ================= 57 57 58 58 What kind of documentation are we talking about ? 59 59 60 A few definitions 60 A few definitions 61 61 ================= 62 62 63 63 Technical documentation that helps to understand how a codebase 64 works and how it can be used. 64 works and how it can be used. 65 65 66 66 This can be: … … 71 71 - a recipe 72 72 73 A few definitions 73 A few definitions 74 74 ================= 75 75 76 76 What is the use and who is the target ? 77 77 78 A few definitions 78 A few definitions 79 79 ================= 80 80 81 81 - Project developers, to... 82 82 … … 99 99 - Writing techniques ans tips: the seven laws 100 100 - Team writing 101 101 102 102 Mastering reSTructuredText 103 103 ========================== … … 170 170 =================== 171 171 172 Focus on your target when you write a document (RÃŒping, 2003). 172 Focus on your target when you write a document (RÃŒping, 2003). 173 173 174 174 Assume their background knowledge to restrict the scope of the documentation. … … 179 179 =================== 180 180 181 A document is about a clear focus. 182 183 A precise title for each section and the document itself, and a summary 181 A document is about a clear focus. 182 183 A precise title for each section and the document itself, and a summary 184 184 can help. 185 185 186 |important| If you cannot easily name the document or one of its section, 186 |important| If you cannot easily name the document or one of its section, 187 187 there's a problem 188 188 … … 197 197 >>> foo = graph.calculateSquare(1, 1, 1, 1) 198 198 >>> bar = graph.renderSquare(foo) 199 200 Better:: 199 200 Better:: 201 201 202 202 >>> from package import graph … … 208 208 209 209 A working software is more important than the best documentation in the world 210 (Ambler, 2002). 210 (Ambler, 2002). 211 211 212 212 *Quality over Quantity* is the best rule. 213 213 214 |important| Spending too much time to find something in the documentation is 214 |important| Spending too much time to find something in the documentation is 215 215 a bad sign. 216 216 217 |important| Think documents like code. Always limit the size of its sections, 217 |important| Think documents like code. Always limit the size of its sections, 218 218 examples, etc. 219 219 … … 229 229 - a toc when there are more than one section 230 230 - references 231 - glossary 231 - glossary 232 232 - tables and diagrams 233 233 … … 249 249 |important| The best pair is made with the end-user 250 250 251 |important| Each document should have a champion, though. 251 |important| Each document should have a champion, though. 252 252 253 253 Team writing … … 260 260 - cooking recipe 261 261 - how to play a board or card game 262 - how to fish shrimps 263 262 - how to fish shrimps 263 264 264 265 265 Writing a document … … 292 292 :height: 350 293 293 :width: 250 294 294 295 295 Developer that write documentation (=winner) 296 296 … … 317 317 The code is documented with: 318 318 319 - inline comments 319 - inline comments 320 320 - functions, classes and modules docstrings 321 321 … … 346 346 - The text file describes what the module does 347 347 348 - example: utils.txt and utils.py 349 350 - Let's practice: exercise #5 |glasses| 348 - example: utils.txt and utils.py 349 350 - Let's practice: exercise #5 |glasses| 351 351 352 352 … … 360 360 - **CHANGELOG**: Lists of changes for each version of the package 361 361 - **INSTALL.txt**: how to install the package 362 - **TODO.txt**: Lists all things to do (sometimes replaced with a 362 - **TODO.txt**: Lists all things to do (sometimes replaced with a 363 363 link to a tracker or a website in README.txt) 364 364 … … 464 464 465 465 - There's 3 level of documentation: 466 466 467 467 - inline comments 468 468 - docstrings 469 469 - separated docstrings 470 470 - Packages comes with mandatory documentation 471 - We can do TDD with doctests, and deal with doc. like code 471 - We can do TDD with doctests, and deal with doc. like code 472 472 473 473 Pause … … 532 532 533 533 - title & abstract (two sentences max) 534 - prerequest: level needed, other documents to read 534 - prerequest: level needed, other documents to read 535 535 - toc (when # sections > 1) 536 536 - body … … 551 551 - A recipe answer to one question, that should be its title. 552 552 553 - Each question is linked to the sentences founded in tutorials. 553 - Each question is linked to the sentences founded in tutorials. 554 554 555 555 - A recipe is short (2 screens) … … 561 561 562 562 - How to code a RSS view ? 563 - How to extract the content of a web page ? 563 - How to extract the content of a web page ? 564 564 565 565 Recipes … … 569 569 570 570 - title & abstract (two sentences max) 571 - prerequest: level needed, other documents to read 571 - prerequest: level needed, other documents to read 572 572 - toc (when # sections > 1) 573 573 - body … … 587 587 - ..avoid using two terms for the same definition 588 588 - ..removes approximacies in documents: 589 not sure on how to explain a concept with simple words ? 589 not sure on how to explain a concept with simple words ? 590 590 look in the glossary |wink| 591 591 … … 639 639 - It is enjoyed by most developers 640 640 641 - It increases both writing and programming skills 641 - It increases both writing and programming skills 642 642 643 643 The end
