SlideShare ist ein Scribd-Unternehmen logo
1 von 40
Downloaden Sie, um offline zu lesen
Documenting from the Trenches

          Xavier Noria
             @fxn
          RuPy 2011
module Globalize
  class MigrationError < StandardError; end
  class MigrationMissingTranslatedField < MigrationError; end
  class BadMigrationFieldType < MigrationError; end

  module ActiveRecord
    autoload :Adapter ,       ’globalize/active_record/adapter’
    autoload :Attributes ,    ’globalize/active_record/attributes’
    autoload :Migration ,     ’globalize/active_record/migration’

    def self.included(base)
      base.extend ActMacro
    end
    ...
  end
end
Infer
Community Drivers


⋆   Documentation tools
⋆   Imitation
⋆   Leaders’ commitment
Perl
$ perldoc IO::String
$ perldoc perl
Literate Programming
Essayists
Works of Literature
docrails
Style


⋆   Typography
⋆   Spelling
⋆   Conventions
Content
⋆   Simple, concise exposition
⋆   Comprehensive coverage
⋆   Well-chosen examples
⋆   Edge-cases
⋆   Anticipation
Documenting ∼ Teaching
# actionpack/lib/action_controller/base.rb
module ActionController
  class Base < Metal
    ...
    MODULES = [
      AbstractController::Layouts ,
      AbstractController::Translation ,
      AbstractController::AssetPaths ,

        ... about two dozen modules
    ]

    MODULES.each do |mod|
      include mod
    end
    ...
  end
end
# activerecord/lib/active_record/validations.rb
module ActiveRecord
  module Validations
    extend ActiveSupport::Concern
    include ActiveModel::Validations

    module ClassMethods
      def create!(attributes = nil, &block)
        if attributes.is_a?(Array)
          attributes.collect { |attr| create!(attr , &block) }
        else
          object = new(attributes)
          yield(object) if block_given?
          object.save!
          object
        end
      end
    end
    ...
  end
end
<!DOCTYPE html>
<html>
<head>
  <title>DefaultLayout</title>
  <%= stylesheet_link_tag :all %>
  <%= javascript_include_tag :defaults %>
  <%= csrf_meta_tag %>
</head>
<body>

<%= yield %>

</body>
</html>
# Returns a meta tag with the cross -site request forgery protection
# token for forms to use. Place this in your head.
def csrf_meta_tag
  if protect_against_forgery?
    %(<meta name=”csrf -param” content=”...”/>n<meta ...>).html_safe
  end
end
# Returns a meta tag with the cross -site request forgery protection
# token for forms to use. Place this in your head.
def csrf_meta_tag
  <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?
    <meta name=”csrf -param” content=”...”/>
    <meta name=”csrf -token” content=”...”/>
  METAS
end
# Returns meta tags ”csrf -param” and ”csrf -token” with the name
# of the cross -site request forgery protection parameter and
# token , respectively.
#
#   <head >
#     <%= csrf_meta_tag %>
#   </head >
#
# These are used to generate the dynamic forms that implement
# non-remote links with <tt>:method </tt>.
#
# Note that regular forms generate hidden fields , and that Ajax
# calls are whitelisted , so they do not use these tags.
def csrf_meta_tag
  <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?
    <meta name=”csrf -param” content=”...”/>
    <meta name=”csrf -token” content=”...”/>
  METAS
end
# Returns meta tags ”csrf -param” and ”csrf -token” with the name
# of the cross -site request forgery protection parameter and
# token , respectively.
#
#   <head >
#     <%= csrf_meta_tags %>
#   </head >
#
# These are used to generate the dynamic forms that implement
# non-remote links with <tt>:method </tt>.
#
# Note that regular forms generate hidden fields , and that Ajax
# calls are whitelisted , so they do not use these tags.
def csrf_meta_tags
  <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?
    <meta name=”csrf -param” content=”...”/>
    <meta name=”csrf -token” content=”...”/>
  METAS
end
# Returns meta tags ”csrf -param” and ”csrf -token” with the name
# of the cross -site request forgery protection parameter and
# token , respectively.
#
#   <head >
#     <%= csrf_meta_tags %>
#   </head >
#
# These are used to generate the dynamic forms that implement
# non-remote links with <tt>:method </tt>.
#
# Note that regular forms generate hidden fields , and that Ajax
# calls are whitelisted , so they do not use these tags.
def csrf_meta_tags
  <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery?
    <meta name=”csrf -param” content=”...”/>
    <meta name=”csrf -token” content=”...”/>
  METAS
end

# For backwards compatibility.
alias csrf_meta_tag csrf_meta_tags
Documentation Maintenance
$ ack csrf_meta_tag
Wish List


⋆   Load + introspect for API
⋆   Link API and tests
⋆   Test coverage for guides
Thanks

Weitere ähnliche Inhalte

Was ist angesagt?

Rest with Java EE 6 , Security , Backbone.js
Rest with Java EE 6 , Security , Backbone.jsRest with Java EE 6 , Security , Backbone.js
Rest with Java EE 6 , Security , Backbone.jsCarol McDonald
 
In memory OLAP engine
In memory OLAP engineIn memory OLAP engine
In memory OLAP engineWO Community
 
Beginners' guide to Ruby on Rails
Beginners' guide to Ruby on RailsBeginners' guide to Ruby on Rails
Beginners' guide to Ruby on RailsVictor Porof
 
.NET Core, ASP.NET Core Course, Session 8
.NET Core, ASP.NET Core Course, Session 8.NET Core, ASP.NET Core Course, Session 8
.NET Core, ASP.NET Core Course, Session 8aminmesbahi
 
An Introduction to Ruby on Rails
An Introduction to Ruby on RailsAn Introduction to Ruby on Rails
An Introduction to Ruby on RailsJoe Fiorini
 
Web Applications and Deployment
Web Applications and DeploymentWeb Applications and Deployment
Web Applications and DeploymentBG Java EE Course
 
OroCRM Partner Technical Training: September 2015
OroCRM Partner Technical Training: September 2015OroCRM Partner Technical Training: September 2015
OroCRM Partner Technical Training: September 2015Oro Inc.
 
JAVA EE DEVELOPMENT (JSP and Servlets)
JAVA EE DEVELOPMENT (JSP and Servlets)JAVA EE DEVELOPMENT (JSP and Servlets)
JAVA EE DEVELOPMENT (JSP and Servlets)Talha Ocakçı
 
Building a Backend with Flask
Building a Backend with FlaskBuilding a Backend with Flask
Building a Backend with FlaskMake School
 
Java Web Programming [2/9] : Servlet Basic
Java Web Programming [2/9] : Servlet BasicJava Web Programming [2/9] : Servlet Basic
Java Web Programming [2/9] : Servlet BasicIMC Institute
 
Jasig Rubyon Rails
Jasig Rubyon RailsJasig Rubyon Rails
Jasig Rubyon RailsPaul Pajo
 
Ruby on Rails: Coding Guideline
Ruby on Rails: Coding GuidelineRuby on Rails: Coding Guideline
Ruby on Rails: Coding GuidelineNascenia IT
 
Java Servlet
Java ServletJava Servlet
Java ServletYoga Raja
 
Using Java to implement SOAP Web Services: JAX-WS
Using Java to implement SOAP Web Services: JAX-WS�Using Java to implement SOAP Web Services: JAX-WS�
Using Java to implement SOAP Web Services: JAX-WSKatrien Verbert
 

Was ist angesagt? (20)

Rest with Java EE 6 , Security , Backbone.js
Rest with Java EE 6 , Security , Backbone.jsRest with Java EE 6 , Security , Backbone.js
Rest with Java EE 6 , Security , Backbone.js
 
Ruby On Rails
Ruby On RailsRuby On Rails
Ruby On Rails
 
Data Access with JDBC
Data Access with JDBCData Access with JDBC
Data Access with JDBC
 
In memory OLAP engine
In memory OLAP engineIn memory OLAP engine
In memory OLAP engine
 
Beginners' guide to Ruby on Rails
Beginners' guide to Ruby on RailsBeginners' guide to Ruby on Rails
Beginners' guide to Ruby on Rails
 
.NET Core, ASP.NET Core Course, Session 8
.NET Core, ASP.NET Core Course, Session 8.NET Core, ASP.NET Core Course, Session 8
.NET Core, ASP.NET Core Course, Session 8
 
An Introduction to Ruby on Rails
An Introduction to Ruby on RailsAn Introduction to Ruby on Rails
An Introduction to Ruby on Rails
 
Web Applications and Deployment
Web Applications and DeploymentWeb Applications and Deployment
Web Applications and Deployment
 
OroCRM Partner Technical Training: September 2015
OroCRM Partner Technical Training: September 2015OroCRM Partner Technical Training: September 2015
OroCRM Partner Technical Training: September 2015
 
JAVA EE DEVELOPMENT (JSP and Servlets)
JAVA EE DEVELOPMENT (JSP and Servlets)JAVA EE DEVELOPMENT (JSP and Servlets)
JAVA EE DEVELOPMENT (JSP and Servlets)
 
Building a Backend with Flask
Building a Backend with FlaskBuilding a Backend with Flask
Building a Backend with Flask
 
Jdbc api
Jdbc apiJdbc api
Jdbc api
 
Java Web Programming [2/9] : Servlet Basic
Java Web Programming [2/9] : Servlet BasicJava Web Programming [2/9] : Servlet Basic
Java Web Programming [2/9] : Servlet Basic
 
Jasig Rubyon Rails
Jasig Rubyon RailsJasig Rubyon Rails
Jasig Rubyon Rails
 
Ruby on Rails: Coding Guideline
Ruby on Rails: Coding GuidelineRuby on Rails: Coding Guideline
Ruby on Rails: Coding Guideline
 
Java Beans
Java BeansJava Beans
Java Beans
 
Java Servlet
Java ServletJava Servlet
Java Servlet
 
Java Server Pages
Java Server PagesJava Server Pages
Java Server Pages
 
Using Java to implement SOAP Web Services: JAX-WS
Using Java to implement SOAP Web Services: JAX-WS�Using Java to implement SOAP Web Services: JAX-WS�
Using Java to implement SOAP Web Services: JAX-WS
 
The CoFX Data Model
The CoFX Data ModelThe CoFX Data Model
The CoFX Data Model
 

Ähnlich wie Documenting from the Trenches

Rails antipatterns
Rails antipatternsRails antipatterns
Rails antipatternsChul Ju Hong
 
Rails antipattern-public
Rails antipattern-publicRails antipattern-public
Rails antipattern-publicChul Ju Hong
 
Metaprogramovanie #1
Metaprogramovanie #1Metaprogramovanie #1
Metaprogramovanie #1Jano Suchal
 
Rails 3 overview
Rails 3 overviewRails 3 overview
Rails 3 overviewYehuda Katz
 
TDC 2012 - Patterns e Anti-Patterns em Ruby
TDC 2012 - Patterns e Anti-Patterns em RubyTDC 2012 - Patterns e Anti-Patterns em Ruby
TDC 2012 - Patterns e Anti-Patterns em RubyFabio Akita
 
Ride on the Fast Track of Web with Ruby on Rails- Part 2
Ride on the Fast Track of Web with Ruby on Rails- Part 2Ride on the Fast Track of Web with Ruby on Rails- Part 2
Ride on the Fast Track of Web with Ruby on Rails- Part 2A.K.M. Ahsrafuzzaman
 
RoR 101: Session 2
RoR 101: Session 2RoR 101: Session 2
RoR 101: Session 2Rory Gianni
 
Exploring Symfony's Code
Exploring Symfony's CodeExploring Symfony's Code
Exploring Symfony's CodeWildan Maulana
 
Rails 3: Dashing to the Finish
Rails 3: Dashing to the FinishRails 3: Dashing to the Finish
Rails 3: Dashing to the FinishYehuda Katz
 
Mojolicious, real-time web framework
Mojolicious, real-time web frameworkMojolicious, real-time web framework
Mojolicious, real-time web frameworktaggg
 
Practical catalyst
Practical catalystPractical catalyst
Practical catalystdwm042
 
Código Saudável => Programador Feliz - Rs on Rails 2010
Código Saudável => Programador Feliz - Rs on Rails 2010Código Saudável => Programador Feliz - Rs on Rails 2010
Código Saudável => Programador Feliz - Rs on Rails 2010Plataformatec
 
Geek Moot '09 -- Smarty 101
Geek Moot '09 -- Smarty 101Geek Moot '09 -- Smarty 101
Geek Moot '09 -- Smarty 101Ted Kulp
 

Ähnlich wie Documenting from the Trenches (20)

Rails antipatterns
Rails antipatternsRails antipatterns
Rails antipatterns
 
Rails antipattern-public
Rails antipattern-publicRails antipattern-public
Rails antipattern-public
 
Metaprogramovanie #1
Metaprogramovanie #1Metaprogramovanie #1
Metaprogramovanie #1
 
Rails 3 overview
Rails 3 overviewRails 3 overview
Rails 3 overview
 
Dsl
DslDsl
Dsl
 
TDC 2012 - Patterns e Anti-Patterns em Ruby
TDC 2012 - Patterns e Anti-Patterns em RubyTDC 2012 - Patterns e Anti-Patterns em Ruby
TDC 2012 - Patterns e Anti-Patterns em Ruby
 
68837.ppt
68837.ppt68837.ppt
68837.ppt
 
Ride on the Fast Track of Web with Ruby on Rails- Part 2
Ride on the Fast Track of Web with Ruby on Rails- Part 2Ride on the Fast Track of Web with Ruby on Rails- Part 2
Ride on the Fast Track of Web with Ruby on Rails- Part 2
 
Rails 4.0
Rails 4.0Rails 4.0
Rails 4.0
 
RoR 101: Session 2
RoR 101: Session 2RoR 101: Session 2
RoR 101: Session 2
 
Exploring Symfony's Code
Exploring Symfony's CodeExploring Symfony's Code
Exploring Symfony's Code
 
Rails 3: Dashing to the Finish
Rails 3: Dashing to the FinishRails 3: Dashing to the Finish
Rails 3: Dashing to the Finish
 
Mojolicious, real-time web framework
Mojolicious, real-time web frameworkMojolicious, real-time web framework
Mojolicious, real-time web framework
 
Wt unit 2 ppts client sied technology
Wt unit 2 ppts client sied technologyWt unit 2 ppts client sied technology
Wt unit 2 ppts client sied technology
 
Wt unit 2 ppts client side technology
Wt unit 2 ppts client side technologyWt unit 2 ppts client side technology
Wt unit 2 ppts client side technology
 
Practical catalyst
Practical catalystPractical catalyst
Practical catalyst
 
The Rails Way
The Rails WayThe Rails Way
The Rails Way
 
Mojolicious
MojoliciousMojolicious
Mojolicious
 
Código Saudável => Programador Feliz - Rs on Rails 2010
Código Saudável => Programador Feliz - Rs on Rails 2010Código Saudável => Programador Feliz - Rs on Rails 2010
Código Saudável => Programador Feliz - Rs on Rails 2010
 
Geek Moot '09 -- Smarty 101
Geek Moot '09 -- Smarty 101Geek Moot '09 -- Smarty 101
Geek Moot '09 -- Smarty 101
 

Mehr von Xavier Noria

Zeitwerk Internals
Zeitwerk InternalsZeitwerk Internals
Zeitwerk InternalsXavier Noria
 
Zeitwerk: a new code loader
Zeitwerk: a new code loaderZeitwerk: a new code loader
Zeitwerk: a new code loaderXavier Noria
 
The Rails Boot Process
The Rails Boot ProcessThe Rails Boot Process
The Rails Boot ProcessXavier Noria
 
Class Reloading in Ruby on Rails: The Whole Story
Class Reloading in Ruby on Rails: The Whole StoryClass Reloading in Ruby on Rails: The Whole Story
Class Reloading in Ruby on Rails: The Whole StoryXavier Noria
 
Numerical ruby-rails-israel-2013
Numerical ruby-rails-israel-2013Numerical ruby-rails-israel-2013
Numerical ruby-rails-israel-2013Xavier Noria
 
I See Your 127.32+, A Tale of Rationals
I See Your 127.32+, A Tale of RationalsI See Your 127.32+, A Tale of Rationals
I See Your 127.32+, A Tale of RationalsXavier Noria
 
Rails Contributors
Rails ContributorsRails Contributors
Rails ContributorsXavier Noria
 

Mehr von Xavier Noria (10)

Zeitwerk Internals
Zeitwerk InternalsZeitwerk Internals
Zeitwerk Internals
 
Zeitwerk: a new code loader
Zeitwerk: a new code loaderZeitwerk: a new code loader
Zeitwerk: a new code loader
 
The Rails Boot Process
The Rails Boot ProcessThe Rails Boot Process
The Rails Boot Process
 
Homage to Perl
Homage to PerlHomage to Perl
Homage to Perl
 
Class Reloading in Ruby on Rails: The Whole Story
Class Reloading in Ruby on Rails: The Whole StoryClass Reloading in Ruby on Rails: The Whole Story
Class Reloading in Ruby on Rails: The Whole Story
 
Numerical Ruby
Numerical RubyNumerical Ruby
Numerical Ruby
 
Numerical ruby-rails-israel-2013
Numerical ruby-rails-israel-2013Numerical ruby-rails-israel-2013
Numerical ruby-rails-israel-2013
 
I See Your 127.32+, A Tale of Rationals
I See Your 127.32+, A Tale of RationalsI See Your 127.32+, A Tale of Rationals
I See Your 127.32+, A Tale of Rationals
 
Rails Contributors
Rails ContributorsRails Contributors
Rails Contributors
 
Revolucion Rails
Revolucion RailsRevolucion Rails
Revolucion Rails
 

Kürzlich hochgeladen

Finology Group – Insurtech Innovation Award 2024
Finology Group – Insurtech Innovation Award 2024Finology Group – Insurtech Innovation Award 2024
Finology Group – Insurtech Innovation Award 2024The Digital Insurer
 
Breaking the Kubernetes Kill Chain: Host Path Mount
Breaking the Kubernetes Kill Chain: Host Path MountBreaking the Kubernetes Kill Chain: Host Path Mount
Breaking the Kubernetes Kill Chain: Host Path MountPuma Security, LLC
 
Data Cloud, More than a CDP by Matt Robison
Data Cloud, More than a CDP by Matt RobisonData Cloud, More than a CDP by Matt Robison
Data Cloud, More than a CDP by Matt RobisonAnna Loughnan Colquhoun
 
Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...
Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...
Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...gurkirankumar98700
 
08448380779 Call Girls In Friends Colony Women Seeking Men
08448380779 Call Girls In Friends Colony Women Seeking Men08448380779 Call Girls In Friends Colony Women Seeking Men
08448380779 Call Girls In Friends Colony Women Seeking MenDelhi Call girls
 
Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...
Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...
Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...Miguel Araújo
 
Slack Application Development 101 Slides
Slack Application Development 101 SlidesSlack Application Development 101 Slides
Slack Application Development 101 Slidespraypatel2
 
A Domino Admins Adventures (Engage 2024)
A Domino Admins Adventures (Engage 2024)A Domino Admins Adventures (Engage 2024)
A Domino Admins Adventures (Engage 2024)Gabriella Davis
 
How to Troubleshoot Apps for the Modern Connected Worker
How to Troubleshoot Apps for the Modern Connected WorkerHow to Troubleshoot Apps for the Modern Connected Worker
How to Troubleshoot Apps for the Modern Connected WorkerThousandEyes
 
Tata AIG General Insurance Company - Insurer Innovation Award 2024
Tata AIG General Insurance Company - Insurer Innovation Award 2024Tata AIG General Insurance Company - Insurer Innovation Award 2024
Tata AIG General Insurance Company - Insurer Innovation Award 2024The Digital Insurer
 
Factors to Consider When Choosing Accounts Payable Services Providers.pptx
Factors to Consider When Choosing Accounts Payable Services Providers.pptxFactors to Consider When Choosing Accounts Payable Services Providers.pptx
Factors to Consider When Choosing Accounts Payable Services Providers.pptxKatpro Technologies
 
The 7 Things I Know About Cyber Security After 25 Years | April 2024
The 7 Things I Know About Cyber Security After 25 Years | April 2024The 7 Things I Know About Cyber Security After 25 Years | April 2024
The 7 Things I Know About Cyber Security After 25 Years | April 2024Rafal Los
 
GenCyber Cyber Security Day Presentation
GenCyber Cyber Security Day PresentationGenCyber Cyber Security Day Presentation
GenCyber Cyber Security Day PresentationMichael W. Hawkins
 
08448380779 Call Girls In Greater Kailash - I Women Seeking Men
08448380779 Call Girls In Greater Kailash - I Women Seeking Men08448380779 Call Girls In Greater Kailash - I Women Seeking Men
08448380779 Call Girls In Greater Kailash - I Women Seeking MenDelhi Call girls
 
Handwritten Text Recognition for manuscripts and early printed texts
Handwritten Text Recognition for manuscripts and early printed textsHandwritten Text Recognition for manuscripts and early printed texts
Handwritten Text Recognition for manuscripts and early printed textsMaria Levchenko
 
Scaling API-first – The story of a global engineering organization
Scaling API-first – The story of a global engineering organizationScaling API-first – The story of a global engineering organization
Scaling API-first – The story of a global engineering organizationRadu Cotescu
 
IAC 2024 - IA Fast Track to Search Focused AI Solutions
IAC 2024 - IA Fast Track to Search Focused AI SolutionsIAC 2024 - IA Fast Track to Search Focused AI Solutions
IAC 2024 - IA Fast Track to Search Focused AI SolutionsEnterprise Knowledge
 
Partners Life - Insurer Innovation Award 2024
Partners Life - Insurer Innovation Award 2024Partners Life - Insurer Innovation Award 2024
Partners Life - Insurer Innovation Award 2024The Digital Insurer
 
Histor y of HAM Radio presentation slide
Histor y of HAM Radio presentation slideHistor y of HAM Radio presentation slide
Histor y of HAM Radio presentation slidevu2urc
 
Automating Google Workspace (GWS) & more with Apps Script
Automating Google Workspace (GWS) & more with Apps ScriptAutomating Google Workspace (GWS) & more with Apps Script
Automating Google Workspace (GWS) & more with Apps Scriptwesley chun
 

Kürzlich hochgeladen (20)

Finology Group – Insurtech Innovation Award 2024
Finology Group – Insurtech Innovation Award 2024Finology Group – Insurtech Innovation Award 2024
Finology Group – Insurtech Innovation Award 2024
 
Breaking the Kubernetes Kill Chain: Host Path Mount
Breaking the Kubernetes Kill Chain: Host Path MountBreaking the Kubernetes Kill Chain: Host Path Mount
Breaking the Kubernetes Kill Chain: Host Path Mount
 
Data Cloud, More than a CDP by Matt Robison
Data Cloud, More than a CDP by Matt RobisonData Cloud, More than a CDP by Matt Robison
Data Cloud, More than a CDP by Matt Robison
 
Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...
Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...
Kalyanpur ) Call Girls in Lucknow Finest Escorts Service 🍸 8923113531 🎰 Avail...
 
08448380779 Call Girls In Friends Colony Women Seeking Men
08448380779 Call Girls In Friends Colony Women Seeking Men08448380779 Call Girls In Friends Colony Women Seeking Men
08448380779 Call Girls In Friends Colony Women Seeking Men
 
Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...
Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...
Mastering MySQL Database Architecture: Deep Dive into MySQL Shell and MySQL R...
 
Slack Application Development 101 Slides
Slack Application Development 101 SlidesSlack Application Development 101 Slides
Slack Application Development 101 Slides
 
A Domino Admins Adventures (Engage 2024)
A Domino Admins Adventures (Engage 2024)A Domino Admins Adventures (Engage 2024)
A Domino Admins Adventures (Engage 2024)
 
How to Troubleshoot Apps for the Modern Connected Worker
How to Troubleshoot Apps for the Modern Connected WorkerHow to Troubleshoot Apps for the Modern Connected Worker
How to Troubleshoot Apps for the Modern Connected Worker
 
Tata AIG General Insurance Company - Insurer Innovation Award 2024
Tata AIG General Insurance Company - Insurer Innovation Award 2024Tata AIG General Insurance Company - Insurer Innovation Award 2024
Tata AIG General Insurance Company - Insurer Innovation Award 2024
 
Factors to Consider When Choosing Accounts Payable Services Providers.pptx
Factors to Consider When Choosing Accounts Payable Services Providers.pptxFactors to Consider When Choosing Accounts Payable Services Providers.pptx
Factors to Consider When Choosing Accounts Payable Services Providers.pptx
 
The 7 Things I Know About Cyber Security After 25 Years | April 2024
The 7 Things I Know About Cyber Security After 25 Years | April 2024The 7 Things I Know About Cyber Security After 25 Years | April 2024
The 7 Things I Know About Cyber Security After 25 Years | April 2024
 
GenCyber Cyber Security Day Presentation
GenCyber Cyber Security Day PresentationGenCyber Cyber Security Day Presentation
GenCyber Cyber Security Day Presentation
 
08448380779 Call Girls In Greater Kailash - I Women Seeking Men
08448380779 Call Girls In Greater Kailash - I Women Seeking Men08448380779 Call Girls In Greater Kailash - I Women Seeking Men
08448380779 Call Girls In Greater Kailash - I Women Seeking Men
 
Handwritten Text Recognition for manuscripts and early printed texts
Handwritten Text Recognition for manuscripts and early printed textsHandwritten Text Recognition for manuscripts and early printed texts
Handwritten Text Recognition for manuscripts and early printed texts
 
Scaling API-first – The story of a global engineering organization
Scaling API-first – The story of a global engineering organizationScaling API-first – The story of a global engineering organization
Scaling API-first – The story of a global engineering organization
 
IAC 2024 - IA Fast Track to Search Focused AI Solutions
IAC 2024 - IA Fast Track to Search Focused AI SolutionsIAC 2024 - IA Fast Track to Search Focused AI Solutions
IAC 2024 - IA Fast Track to Search Focused AI Solutions
 
Partners Life - Insurer Innovation Award 2024
Partners Life - Insurer Innovation Award 2024Partners Life - Insurer Innovation Award 2024
Partners Life - Insurer Innovation Award 2024
 
Histor y of HAM Radio presentation slide
Histor y of HAM Radio presentation slideHistor y of HAM Radio presentation slide
Histor y of HAM Radio presentation slide
 
Automating Google Workspace (GWS) & more with Apps Script
Automating Google Workspace (GWS) & more with Apps ScriptAutomating Google Workspace (GWS) & more with Apps Script
Automating Google Workspace (GWS) & more with Apps Script
 

Documenting from the Trenches

  • 1. Documenting from the Trenches Xavier Noria @fxn RuPy 2011
  • 2.
  • 3.
  • 4. module Globalize class MigrationError < StandardError; end class MigrationMissingTranslatedField < MigrationError; end class BadMigrationFieldType < MigrationError; end module ActiveRecord autoload :Adapter , ’globalize/active_record/adapter’ autoload :Attributes , ’globalize/active_record/attributes’ autoload :Migration , ’globalize/active_record/migration’ def self.included(base) base.extend ActMacro end ... end end
  • 6.
  • 7.
  • 8.
  • 9. Community Drivers ⋆ Documentation tools ⋆ Imitation ⋆ Leaders’ commitment
  • 10. Perl
  • 11.
  • 12.
  • 14.
  • 16.
  • 17.
  • 18.
  • 22.
  • 23.
  • 24.
  • 26. Style ⋆ Typography ⋆ Spelling ⋆ Conventions
  • 27. Content ⋆ Simple, concise exposition ⋆ Comprehensive coverage ⋆ Well-chosen examples ⋆ Edge-cases ⋆ Anticipation
  • 29. # actionpack/lib/action_controller/base.rb module ActionController class Base < Metal ... MODULES = [ AbstractController::Layouts , AbstractController::Translation , AbstractController::AssetPaths , ... about two dozen modules ] MODULES.each do |mod| include mod end ... end end
  • 30. # activerecord/lib/active_record/validations.rb module ActiveRecord module Validations extend ActiveSupport::Concern include ActiveModel::Validations module ClassMethods def create!(attributes = nil, &block) if attributes.is_a?(Array) attributes.collect { |attr| create!(attr , &block) } else object = new(attributes) yield(object) if block_given? object.save! object end end end ... end end
  • 31. <!DOCTYPE html> <html> <head> <title>DefaultLayout</title> <%= stylesheet_link_tag :all %> <%= javascript_include_tag :defaults %> <%= csrf_meta_tag %> </head> <body> <%= yield %> </body> </html>
  • 32. # Returns a meta tag with the cross -site request forgery protection # token for forms to use. Place this in your head. def csrf_meta_tag if protect_against_forgery? %(<meta name=”csrf -param” content=”...”/>n<meta ...>).html_safe end end
  • 33. # Returns a meta tag with the cross -site request forgery protection # token for forms to use. Place this in your head. def csrf_meta_tag <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery? <meta name=”csrf -param” content=”...”/> <meta name=”csrf -token” content=”...”/> METAS end
  • 34. # Returns meta tags ”csrf -param” and ”csrf -token” with the name # of the cross -site request forgery protection parameter and # token , respectively. # # <head > # <%= csrf_meta_tag %> # </head > # # These are used to generate the dynamic forms that implement # non-remote links with <tt>:method </tt>. # # Note that regular forms generate hidden fields , and that Ajax # calls are whitelisted , so they do not use these tags. def csrf_meta_tag <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery? <meta name=”csrf -param” content=”...”/> <meta name=”csrf -token” content=”...”/> METAS end
  • 35. # Returns meta tags ”csrf -param” and ”csrf -token” with the name # of the cross -site request forgery protection parameter and # token , respectively. # # <head > # <%= csrf_meta_tags %> # </head > # # These are used to generate the dynamic forms that implement # non-remote links with <tt>:method </tt>. # # Note that regular forms generate hidden fields , and that Ajax # calls are whitelisted , so they do not use these tags. def csrf_meta_tags <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery? <meta name=”csrf -param” content=”...”/> <meta name=”csrf -token” content=”...”/> METAS end
  • 36. # Returns meta tags ”csrf -param” and ”csrf -token” with the name # of the cross -site request forgery protection parameter and # token , respectively. # # <head > # <%= csrf_meta_tags %> # </head > # # These are used to generate the dynamic forms that implement # non-remote links with <tt>:method </tt>. # # Note that regular forms generate hidden fields , and that Ajax # calls are whitelisted , so they do not use these tags. def csrf_meta_tags <<-METAS.strip_heredoc.chomp.html_safe if protect_against_forgery? <meta name=”csrf -param” content=”...”/> <meta name=”csrf -token” content=”...”/> METAS end # For backwards compatibility. alias csrf_meta_tag csrf_meta_tags
  • 39. Wish List ⋆ Load + introspect for API ⋆ Link API and tests ⋆ Test coverage for guides