Getting Started with Documentation in Rails

Transcript

1. Getting Started with Documentation in Rails Danielle Tucker
2. Types of Documentation • Requirements • Design • Marketing • End User • Technical http://www.informit.com/articles/article.aspx?p=29888 http://en.wikipedia.org/wiki/Software_documentation
3. How Much?
4. Enough How Much?
5. Why Should I? • Communication with other Developers and Contributors • Reminders to Future You • Usability (especially with a public API) • More Docs = Better Perceived Quality
6. Documentation Should Answer Two Questions • What does it do? • How do I use it? – Readme – Testing Suite – Inline Comments – Rdocs – Other Goodies
7. Have A Readme !! Elements of a Good Readme • Description What problem does this solve? • Installation Instructions How do I get this thing working? • Links to More Docs Ok I want more info, now what? • How to Contribute This is cool, how can I join? • Credits, Alternatives Where did this idea come from? http://warpspire.com/talks/documentation/ http://xkcd.com/293/
8. Have A Readme !! Elements of a Good Readme • Description What problem does this solve? • Installation Instructions How do I get this thing working? • Links to More Docs Ok I want more info, now what? • How to Contribute This is cool, how can I join? • Credits, Alternatives Where did this idea come from? http://warpspire.com/talks/documentation/ http://xkcd.com/293/
9. Rails Helps You Out... In General Following the Rails Conventions goes a long way to documenting your code • Use Good descriptive naming • Most methods are short http://geekandpoke.typepad.com/geekandpoke/2013/02/self-documenting-code.html
10. Rails Helps You Out... DHH on documenting his projects... • "The short answer is that we don't document our projects [...] most Rails programmers would know their way around our applications straight away. It's the same conventions and pattern throughout...." • That’s not to say that there are no code comments in our code bases. Just very little. And usually only to describe something that looks like it shouldn’t be the way that it is. Something counterintuitive. http://37signals.com/svn/posts/838-ask-37signals-how-do-you-document-code? 34#all_comments
11. Yet Another Reason Why BDD Rocks
12. Auto-Generated Documentation • RDocs / SDocs • Yard • Annotate • Rails ERD • And more... http://findicons.com/icon/69384/wizard1?id=277787
13. • Classic documentation tool • Creates HTML documentation from source • Uses the comments in source to create Its Simple: Run (In the root dir of you app) rake doc:app Main page at: doc/app/index.html *Change the README_FOR_APP
15. Commenting Your Source • RDocs Markup style is similar to wiki pages markup • Also supports Markdown, Rd, TomDoc, and even your own style! • Markup Guides Cheat Sheet http://jan.varwig.org/wp-content/uploads/2006/09/Rdoc%20Cheat%20Sheet.pdf RDoc Example for documenting classes and methods http://blog.firsthand.ca/2010/09/ruby-rdoc-example.html Rdoc::Markup Documentation http://rdoc.rubyforge.org/RDoc/Markup.html
16. Code Comment Basics • Keep it short and sweet • Write in present tense... #Returns a cat that is in attack mode instead of #Returned a cat that is in attack mode • Document any edge cases (What happens if the cat is already in that mode?) • Basic contents: - Description - Parameters and Options - Examples of Usage http://guides.rubyonrails.org/api_documentation_guidelines.html
17. Example: Rails Form Helper Method
18. Example: Rails Form Helper Method • As rendered on api.rubyonrails.org • Looks different as they are using SDoc - builds a more searchable API - still supports the Rdoc markup - Rails API using SDoc since 3.1
19. YARD (Yay! A Ruby Documentation Tool) yardoc.org - builds upon RDoc but has some extra features - supports a variety of markup formats - has tools to view documentation as you write it - adds tags to make comments shorter and add metadata @return [Cat] the feline in attack mode @author Devilish God
20. YARD Example YARD Classic RDoc http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
21. Other Documentation Tools • Annotate github.com/ctran/annotate_models - summarize you db model - add your routes to your routes.rb • Rails ERD github.com/voormedia/rails-erd -visualize your models and their relationships
22. What's Next? • See what happens when you use the built in RDoc in rails • Start small • Keep it Simple • Explore