Ruby Rogues

Ruby Rogues

Our original panel podcast, Ruby Rogues is a weekly discussion around Ruby, Rails, software development, and the community around Ruby.Become a supporter of this podcast: https://www.spreaker.com/podcast/ruby-rogues--6102073/support.

https://topenddevs.com/podcasts/ruby-rogues

Technology
Business Careers
Education How to
subscribe
share






support
claim!
report

RR 424: Documenting Your Code

Sponsors

  • Sentry use code “devchat” for $100 credit
  • Datadog
Panel
  • David Kimura
  • Nate Hopkins
  • Andrew Mason
Episode SummaryToday the panel is talking about documentation. They begin by discussing what documentation is, where it fits within an application, and if the code documents itself. They agree that documentation starts in the comments to explain what you’re doing, but if that’s your exclusive method, then a refactor is in order. They talk about where to start with documentation and different ways they’ve done it. The panel talks about the importance of documentation, especially for people just joining a team. In addition to documenting the project itself, it is important to document what different libraries do and how to interact with them. They discuss where to put this kind of documentation. They talk about documenting patterns, best practices, and procedures in addition to the ‘how to’ of a project. The conversation turns to style guidelines, what they are, and how to keep them up to date. They talk about what tools are available to generate documentation that are close to the code but outside of it that can help keep documentation up to date. The panel believes that there is a relationship between the size of your team and the necessity to document. Nate introduces the idea found in the article by Tom Preston-Werner that you should think about what you’re going to create in the code, and document it first. Links
  • RDoc
  • YARD 
  • RuboCop
  • YAML
  • Slim
  • ERB
  • Prettier
  • Pronto
  • Api.rubyonrails.org
  • Swagger
  • Thoughtbot and Thoughtbot Playbook
  • AirBNB Ruby
  • Testdouble
  • HoundCI
  • Okonet
  • API Blueprint
  • Ruby on Rails API documentation guidelines
  • Tom Preston-Werner article Readme Driven Development
Follow DevChat on Facebook and Twitter PicksNate Hopkins:
  • Code Fund
Andrew Mason:
  • SpaceVIM
  • RailsDiff
  • Rails Releases
David Kimura:
  • Jackery Supercharger Portable


Advertising Inquiries: https://redcircle.com/brands

Privacy & Opt-Out: https://redcircle.com/privacy

fyyd: Podcast Search Engine
share








 August 6, 2019  40m