Write A Better FM - Ohio Linux 2011

1,484 views

Published on

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,484
On SlideShare
0
From Embeds
0
Number of Embeds
15
Actions
Shares
0
Downloads
8
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Write A Better FM - Ohio Linux 2011

    1. 1. Write A Better FM / Rich Bowen - rbowen@apache.org
    2. 2. Thats Kathy Sierra Shes amazing
    3. 3. Disclaimer • These are my OPINIONS, and, as such, are probably wrong in many projects/products/communities. • Mostly the result of ten years on the Apache HTTP Server documentation project
    4. 4. Everybody knows ... • Documentation in Open Source is terrible • Nobody wants to do it • This is simply a reality of Open Source, and we have to put up with it
    5. 5. Counterexample: • PHPs docs are pretty much the best available in Open Source today • Bias: Im (sort of) on the PHP docs team.
    6. 6. Why are the PHP docs awesome? • Organized docs team outside of the dev team • Smart decisions about formats • Welcoming of contributions and criticisms • Documentation respected at the top level • And: https://edit.php.net/
    7. 7. So what? • Documentation is a priority • Its worth devoting resources to it • Documentation authors are not second-class citizens
    8. 8. The Truth • Lots of people want to write docs (some of them can even write a coherent sentence) • We make it way too hard for them to participate • So they flock to third-party forums, where they share misconceptions and worst- practice "solutions."
    9. 9. Have you noticed? The more likely a "support" channel is to say "RTFM", the worse the documentation is likely to be.
    10. 10. Smart Questions: Eric RaymondRTFM and STFW: How To Tell Youve Seriously ScrewedUpThere is an ancient and hallowed tradition: if you get areply that reads “RTFM”, the person who sent it thinksyou should have Read The F***ing Manual. He or she isalmost certainly right. Go read it.RTFM has a younger relative. If you get a reply that reads“STFW”, the person who sent it thinks you should haveSearched The F*ing Web. He or she is almost certainlyright. Go search it. (The milder version of this is whenyou are told “Google is your friend!”)
    11. 11. Eric Is Wrong It is not a "hallowed tradition". Its bad manners, and its juvenile. Its time to grow up.CC Jumer, Flickr
    12. 12. RTFM The RTFM attitude is indicative of arrogance and impatience, whereas truly great documentation is the result of patience and humility (Yes, they should read the docs. No, you should not be rude.)
    13. 13. Questions to consider: What is the "right" scope for the documentation? • What should the documentation cover? • How should we go about getting there?
    14. 14. Or, stated differently: "Your documentation is inadequate for my specific weirdo situation." • Should we care? • What should we do about it?
    15. 15. Document ScopeMost projects never askthese questions, which is • What should thewhy documentation cover? their documentation • is so awful. How should we go about getting there?
    16. 16. Document scope: The Right Answer • There is not necessarily a single right answer • However, it is important to decide on an answer, and stick to it
    17. 17. Question 2Who are you addressing in your documentation? • Usually (at least) two answers to this: • Developers (core product - API docs) • Customizers (how do I make it do X?) • End-users (Just make the darned thing work?)
    18. 18. Audience => Concerns • Just make it work • Security • Performance • Maintenance
    19. 19. Audience => Concerns • Just make it work all These are • Security questions valid • Performance • Maintenance
    20. 20. PHP: Audiences • Core developers (API docs) • Server admins (install, configure, security) • Programmers (Reference manual) • Hobbyists (I just wanna ...) • Maintainers (This product is written in php and ...)
    21. 21. Apache HTTP Server: Audiences • Developers (core) • Developers (Third-party modules) • Server admins (install, configure, secure) • Developers (stuff on top of Apache) • Website developers (HTML, Javascript, CSS) • Users of third-party products that live on top of Apache
    22. 22. Drupal: Audiences • Developers (core) • Developers (extensions) • Theme developers • System admins • End users • All of these folks also need the PHP docs and the Apache docs, but may come to us with their seemingly off-topic questions
    23. 23. Good
    24. 24. Not so good
    25. 25. Terrible
    26. 26. Clarification: • Its not the mysql documentation that is terrible • Its the way the front page of the docs says "Go Away You Criminal" • Its the FBI Warning of Open Source documentation
    27. 27. Will it ever end?
    28. 28. Will it ever end?
    29. 29. Will it ever end?
    30. 30. Yes, its all one page
    31. 31. So what? • You need to answer the kinds of questions theyre likely to have • You need to respect each audience, while not ignoring any of them • There is, of course, HUGE overlap • But also there are areas that are only of interest to one audience or the other
    32. 32. Remember also that your audience are not all white american males Inside jokes and cultural references are unprofessional ... usuallyCC alexkess, Flickr
    33. 33. Haystack • My favorite function doc, anywhere • Immediately obvious • But how does it work for folks that arent as proficient in English?
    34. 34. Lovely Plumage
    35. 35. Codex
    36. 36. Wordpress • Wordpress are a bunch of spoilsports • Their docs used to be worth at least a half-dozen slides
    37. 37. Apache HTTP Server
    38. 38. So ... hernan.seoane, Flickr CC • Once you think you know who your audience is ...
    39. 39. What questions are they asking? • When your product is young, you answer the questions that you expect to be asked • As it matures, you should listen to whats actually being asked
    40. 40. What questions are they asking? Most documentation never progresses past this point • When your product is young, you answer the questions that you expect to be asked • As it matures, you should listen to whats actually being asked
    41. 41. How docs are born • Documentation tends to have one of two beginnings • Proactive: What do we think people will ask? • Reactive: What are people asking?
    42. 42. What are the questions? • You have to actually listen • You have to go where theyre asking • Mailing lists • IRC • Third-party forums • Their questions matter to them. Be respectful
    43. 43. A word about IRC: • You are brutal on IRC and on your users support mailing list • You treat every question as though the questioner has brain damage, and is beneath your scorn • The exceptions to this are so uncommon that they seem shocking when you encounter common courtesy.
    44. 44. The three virtues CC Sarahkim, Flickr • Laziness • Impatience • Hubris
    45. 45. Laziness • Answer the question thoroughly, once • Save your answer • Next time, give them a URL • Better to do something well, once, than do to it poorly, again and again
    46. 46. Patience • Impatience with the question comes across as disrespect for the questioner • Arrogance and disrespect are at the heart of the RTFM mindset • If you cannot be patient, please let someone else answer the question
    47. 47. Patience Love is patient, love is kind ... itdoes not keep a record of offenses. (I Corinthians 13 - The Bible)
    48. 48. Humility • You dont know everything • The documentation isnt perfect yet • Remember that once you, too, were completely ignorant
    49. 49. FALSE• Theres no such thing as the wrong question: False - but its your job to guide them to the right question, and its answer• Theres no such thing as a stupid question (but there are a lot of inquisitive idiots)
    50. 50. How do we answer them? • Reference manual • HowTos • FAQs • Examples
    51. 51. Reference Manual • Comprehensive and exhaustive • Correct • Consistent format • Best practice • Lots of examples • All examples must be tested
    52. 52. Correct • Obvious, right? • Youd think
    53. 53. Comprehensive • What the heck are sprintf(3) and printf(3)? • I came here for the general principles
    54. 54. Comprehensive • However ... "Comprehensive" needs to be clearly defined • Do the PHP docs need to cover the history of computing? • Do the Apache docs need to cover HTML? • (i.e., you need to know your answer to question #1)
    55. 55. Consistent format
    56. 56. Consistent Format
    57. 57. Best practice • Beginners often just want it to work • The best answer is often more complicated than the good enough answer • Doing it right now saves time and tears later
    58. 58. Third-party "documentation" • Usually focused on "good enough" • Thus usually insecure, inefficient, or fragile
    59. 59. Almost right ...
    60. 60. Examples • Simple • Copious • Tested • Consistent use of a fictitious site/project/ implementation
    61. 61. Examples: Simple • Simplest example that illustrates the concept • Explained in exhaustive detail • Perhaps followed by more complex examples
    62. 62. The curse of simple examples If an example is simple enough toexplain in a paragraph, theres a goodchance its not a very good example. RewriteRule ^/(designer|typeface|foundry|project|supplement|typeface_category)/?([^/]+)?/?(d+)?$ http:// localhost:8080/$1.html?name=$2&page=$3 [P,QSA,L] Corollary: A really good example which takes 8 pages to explain is not a good example.
    63. 63. Examples: Copious • More examples are always better than fewer • ... if they are useful examples • ... and are explained adequately • OReillys Cookbooks are consistently best- sellers
    64. 64. Example from the Apache 1.3mod_rewrite documentation
    65. 65. Examples: Tested • Few things spread faster than incorrect examples • Test every example. Even ones that seem trivial • Incorrect examples lead to many, many hours of lost productivity
    66. 66. Test::POD • The examples are in the documentation, and automatically become tests • Its practically magic
    67. 67. Examples Inc. • Construct an imaginary project/company/site/ whatever • Consistently refer to it in the documentation • example.org or Acme Widgets, Inc, for example • Changing the hero of your story in the middle confuses the reader
    68. 68. Examples: Useful<h1>El Jefes Tours</h1><form action="path to setECURL" method="post"><input id="submitBtn" type="submit" value="Pay with PayPal" /><input type="hidden" name="success_url" value="path to successURL" /><input type="hidden" name="cancel_url" value="path to cancelURL"></form><!-- End custom merchant code --><!-- Example courtesy of PayPal documentation -->
    69. 69. Examples: Useful<h1>El Jefes Tours</h1> It took two hours<form action="path to setECURL" method="post"><input id="submitBtn" type="submit" the wrong to find value="Pay with PayPal" /> value, and a<input type="hidden" name="success_url" further hour to value="path to successURL" /><input type="hidden" name="cancel_url" find the right value="path to cancelURL"></form> value ... which still<!-- End custom merchant code --> didnt work.
    70. 70. PayPal • I will spare you any more PayPal examples • Mocking the PayPal documentation is a little like kicking puppies • At least they are aware that their documentation is terrible, and so provide great online support (Twitter, Forums) Flickr: g-mikee
    71. 71. HowTos and Tutorials • Complete - cover even the trivial steps. • Never say "easy", "trivial", "simple", or "of course". Your reader is there because its not. • Test it. Repeatedly. On multiple systems. • Let your inexperienced co-workers read it.
    72. 72. HowTos and Tutorials • Complete - cover even the trivial steps. This is a delicate balance - between deciding whats in scope, and not leaving them to figure out everything on their own
    73. 73. Dont mock your customers
    74. 74. FAQs • FAQs are often an admission that the documentation is insufficient • Should be a call for improving the docs, or even a scratch-pad for the new docs • Most FAQs should be answered with "heres where thats covered in the docs."
    75. 75. Documentation format • The choice of a documentation format can be quite divisive • Choosing wrong can lead to many problems • Of course, there is no right choice, either
    76. 76. Format considerations • Easy to edit • Multiple output formats • Translation-friendly • Text (ie, non-binary format) • Revision control
    77. 77. Options include • Docbook or other XML • Wikis (Makes translation difficult) • POD (In certain cultures) • JavaDoc (or phpdoc, or rubydoc) • If other projects in the same space have a consistent format, dont try to be clever
    78. 78. Searchable • Excellent documentation without a decent search isnt worth anything • There is no excuse for not having a good search. Google will do it for you for free. CC Stéfan, Flickr
    79. 79. Encouraging participation • Make it easy for people to complain • Take their complaints seriously • Dont get offended when they tell you the docs suck • Do something about it
    80. 80. PHP • PHP does this really well
    81. 81. ... but • Theyre pretty much alone in this
    82. 82. Everyone else: • Create an account I just wanted to tell you that you • Get a checkout misspelled • Subscribe to this list "peony" • Create a ticket in Bugzilla • Email a patch • Follow up on that list
    83. 83. Git • Half of you are itching to tell me that Git solves this problem • This may in fact be true for certain projects
    84. 84. Welcome contributions • Make it obvious how to submit comments, improvements, errata • Dont ignore them once theyre submitted • Be quick to offer commit rights to repeat customers
    85. 85. Going to the source • The developers (often) dont like writing docs • When they realize you do, theyll be willing to answer your questions
    86. 86. Also, the source• Learn to read the source code• It will save you many tears in the long run• However, dont require programming knowledge to participate in the documentation
    87. 87. Error messages • Error messages are documentation, too else if (!(status & LP_PERRORP)) { if (last != LP_PERRORP) { last = LP_PERRORP; printk(KERN_INFO "lp%d on firen", minor); } } Linux printer driver, circa 2.2.1
    88. 88. How much to say • What should the documentation not cover? • You must decide what things are outside of the scope • Once you cross the line, youll end up writing books, and down that road lies madness
    89. 89. Work for it We have a tendency to want to make them work for the information, either in a mistaken notion that this will make them remember it, or merely because we had to work for it, so they should too Well, in my day, we had to edit the inodes with a bar magnet! Go figure it out yourself, punk! CC by hiro008, flickr
    90. 90. Harness the whining cc cindy47452 flickr • Whiners -> Contributors: HARD, but worthwhile • Potential contributors -> Whiners: EASY
    91. 91. Your documentation sucks Shut up.Youre ugly and your mother dresses you funny. Result:Your documentation still sucks, andyouve alienated someone who wanted, albeit misguidedly, to help.
    92. 92. Your documentation sucks How do you think we could improve it?Result: Your documentation might get better,and, even if it doesnt, youve told one person that you care what your customers think.
    93. 93. Questions? • rbowen@apache.org • http://slideshare.net/rbowen <-- Slides here • http://betterfm.org/ • http://redwoodopen.org/ • http://omniti.com/is/hiring

    ×