SlideShare a Scribd company logo
1 of 40
Download to read offline
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

More Related Content

What's hot

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
 

What's hot (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
 

Similar to 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
 

Similar to 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
 

More from 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
 

More from 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
 

Recently uploaded

[Webinar] SpiraTest - Setting New Standards in Quality Assurance
[Webinar] SpiraTest - Setting New Standards in Quality Assurance[Webinar] SpiraTest - Setting New Standards in Quality Assurance
[Webinar] SpiraTest - Setting New Standards in Quality AssuranceInflectra
 
Landscape Catalogue 2024 Australia-1.pdf
Landscape Catalogue 2024 Australia-1.pdfLandscape Catalogue 2024 Australia-1.pdf
Landscape Catalogue 2024 Australia-1.pdfAarwolf Industries LLC
 
Bridging Between CAD & GIS: 6 Ways to Automate Your Data Integration
Bridging Between CAD & GIS:  6 Ways to Automate Your Data IntegrationBridging Between CAD & GIS:  6 Ways to Automate Your Data Integration
Bridging Between CAD & GIS: 6 Ways to Automate Your Data Integrationmarketing932765
 
Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24
Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24
Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24Mark Goldstein
 
Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024Hiroshi SHIBATA
 
Abdul Kader Baba- Managing Cybersecurity Risks and Compliance Requirements i...
Abdul Kader Baba- Managing Cybersecurity Risks  and Compliance Requirements i...Abdul Kader Baba- Managing Cybersecurity Risks  and Compliance Requirements i...
Abdul Kader Baba- Managing Cybersecurity Risks and Compliance Requirements i...itnewsafrica
 
Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024TopCSSGallery
 
Testing tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examplesTesting tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examplesKari Kakkonen
 
Microservices, Docker deploy and Microservices source code in C#
Microservices, Docker deploy and Microservices source code in C#Microservices, Docker deploy and Microservices source code in C#
Microservices, Docker deploy and Microservices source code in C#Karmanjay Verma
 
Connecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdfConnecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdfNeo4j
 
Assure Ecommerce and Retail Operations Uptime with ThousandEyes
Assure Ecommerce and Retail Operations Uptime with ThousandEyesAssure Ecommerce and Retail Operations Uptime with ThousandEyes
Assure Ecommerce and Retail Operations Uptime with ThousandEyesThousandEyes
 
Kuma Meshes Part I - The basics - A tutorial
Kuma Meshes Part I - The basics - A tutorialKuma Meshes Part I - The basics - A tutorial
Kuma Meshes Part I - The basics - A tutorialJoão Esperancinha
 
The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...
The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...
The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...Wes McKinney
 
A Framework for Development in the AI Age
A Framework for Development in the AI AgeA Framework for Development in the AI Age
A Framework for Development in the AI AgeCprime
 
QCon London: Mastering long-running processes in modern architectures
QCon London: Mastering long-running processes in modern architecturesQCon London: Mastering long-running processes in modern architectures
QCon London: Mastering long-running processes in modern architecturesBernd Ruecker
 
Design pattern talk by Kaya Weers - 2024 (v2)
Design pattern talk by Kaya Weers - 2024 (v2)Design pattern talk by Kaya Weers - 2024 (v2)
Design pattern talk by Kaya Weers - 2024 (v2)Kaya Weers
 
Digital Tools & AI in Career Development
Digital Tools & AI in Career DevelopmentDigital Tools & AI in Career Development
Digital Tools & AI in Career DevelopmentMahmoud Rabie
 
Decarbonising Buildings: Making a net-zero built environment a reality
Decarbonising Buildings: Making a net-zero built environment a realityDecarbonising Buildings: Making a net-zero built environment a reality
Decarbonising Buildings: Making a net-zero built environment a realityIES VE
 
Time Series Foundation Models - current state and future directions
Time Series Foundation Models - current state and future directionsTime Series Foundation Models - current state and future directions
Time Series Foundation Models - current state and future directionsNathaniel Shimoni
 
A Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software DevelopersA Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software DevelopersNicole Novielli
 

Recently uploaded (20)

[Webinar] SpiraTest - Setting New Standards in Quality Assurance
[Webinar] SpiraTest - Setting New Standards in Quality Assurance[Webinar] SpiraTest - Setting New Standards in Quality Assurance
[Webinar] SpiraTest - Setting New Standards in Quality Assurance
 
Landscape Catalogue 2024 Australia-1.pdf
Landscape Catalogue 2024 Australia-1.pdfLandscape Catalogue 2024 Australia-1.pdf
Landscape Catalogue 2024 Australia-1.pdf
 
Bridging Between CAD & GIS: 6 Ways to Automate Your Data Integration
Bridging Between CAD & GIS:  6 Ways to Automate Your Data IntegrationBridging Between CAD & GIS:  6 Ways to Automate Your Data Integration
Bridging Between CAD & GIS: 6 Ways to Automate Your Data Integration
 
Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24
Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24
Arizona Broadband Policy Past, Present, and Future Presentation 3/25/24
 
Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024Long journey of Ruby standard library at RubyConf AU 2024
Long journey of Ruby standard library at RubyConf AU 2024
 
Abdul Kader Baba- Managing Cybersecurity Risks and Compliance Requirements i...
Abdul Kader Baba- Managing Cybersecurity Risks  and Compliance Requirements i...Abdul Kader Baba- Managing Cybersecurity Risks  and Compliance Requirements i...
Abdul Kader Baba- Managing Cybersecurity Risks and Compliance Requirements i...
 
Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024Top 10 Hubspot Development Companies in 2024
Top 10 Hubspot Development Companies in 2024
 
Testing tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examplesTesting tools and AI - ideas what to try with some tool examples
Testing tools and AI - ideas what to try with some tool examples
 
Microservices, Docker deploy and Microservices source code in C#
Microservices, Docker deploy and Microservices source code in C#Microservices, Docker deploy and Microservices source code in C#
Microservices, Docker deploy and Microservices source code in C#
 
Connecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdfConnecting the Dots for Information Discovery.pdf
Connecting the Dots for Information Discovery.pdf
 
Assure Ecommerce and Retail Operations Uptime with ThousandEyes
Assure Ecommerce and Retail Operations Uptime with ThousandEyesAssure Ecommerce and Retail Operations Uptime with ThousandEyes
Assure Ecommerce and Retail Operations Uptime with ThousandEyes
 
Kuma Meshes Part I - The basics - A tutorial
Kuma Meshes Part I - The basics - A tutorialKuma Meshes Part I - The basics - A tutorial
Kuma Meshes Part I - The basics - A tutorial
 
The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...
The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...
The Future Roadmap for the Composable Data Stack - Wes McKinney - Data Counci...
 
A Framework for Development in the AI Age
A Framework for Development in the AI AgeA Framework for Development in the AI Age
A Framework for Development in the AI Age
 
QCon London: Mastering long-running processes in modern architectures
QCon London: Mastering long-running processes in modern architecturesQCon London: Mastering long-running processes in modern architectures
QCon London: Mastering long-running processes in modern architectures
 
Design pattern talk by Kaya Weers - 2024 (v2)
Design pattern talk by Kaya Weers - 2024 (v2)Design pattern talk by Kaya Weers - 2024 (v2)
Design pattern talk by Kaya Weers - 2024 (v2)
 
Digital Tools & AI in Career Development
Digital Tools & AI in Career DevelopmentDigital Tools & AI in Career Development
Digital Tools & AI in Career Development
 
Decarbonising Buildings: Making a net-zero built environment a reality
Decarbonising Buildings: Making a net-zero built environment a realityDecarbonising Buildings: Making a net-zero built environment a reality
Decarbonising Buildings: Making a net-zero built environment a reality
 
Time Series Foundation Models - current state and future directions
Time Series Foundation Models - current state and future directionsTime Series Foundation Models - current state and future directions
Time Series Foundation Models - current state and future directions
 
A Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software DevelopersA Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software Developers
 

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