Eric Holscher on Documentation and Read The Docs

Visit our site to listen to past episodes, support the show, and sign up for our mailing list.

Summary

The first place we all go for learning about new libraries is the documentation. Lack of effective documentation can limit the adoption of an otherwise excellent project. In this episode we spoke with Eric Holscher, co-creator of Read The Docs, about why documentation is important and how we can all work to make it better.

Brief Introduction

• Hello and welcome to Podcast.__init__, the podcast about Python and the people who make it great.
• Subscribe on iTunes, Stitcher, TuneIn or RSS
• Follow us on Twitter or Google+
• Give us feedback! Leave a review on iTunes, Tweet to us, send us an email or leave us a message on Google+
• I would like to thank everyone who has donated to the show. Your contributions help us make the show sustainable. For details on how to support the show you can visit our site at pythonpodcast.com
• I would also like to thank Hired, a job marketplace for developers, for sponsoring this episode of Podcast.__init__. Use the link hired.com/podcastinit to double your signing bonus.
• Linode is sponsoring us this week. Check them out at linode.com/podcastinit and get a $10 credit to try out their fast and reliable Linux virtual servers for your next project
• We are recording today on November 30th, 2015 and your hosts as usual are Tobias Macey and Chris Patti
• Today we are interviewing Eric Holscher about Documentation

Use the promo code podcastinit10 to get a $10 credit when you sign up!

On Hired software engineers & designers can get 5+ interview requests in a week and each offer has salary and equity upfront. With full time and contract opportunities available, users can view the offers and accept or reject them before talking to any company. Work with over 2,500 companies from startups to large public companies hailing from 12 major tech hubs in North America and Europe. Hired is totally free for users and If you get a job you’ll get a $2,000 “thank you” bonus. If you use our special link to signup, then that bonus will double to $4,000 when you accept a job. If you’re not looking for a job but know someone who is, you can refer them to Hired and get a $1,337 bonus when they accept a job.

Interview with Eric Holscher

• Introductions
• How did you get introduced to Python? – Chris
• You are one of the people behind the Read The Docs project. What was your inspiration for creating that platform and why is documentation so important in software? – Tobias
• What makes Read The Docs different from other static sources for documentation? – Chris
• The Python community seems to have a stronger focus on well-documented projects than some other languages. Do you have any theories as to why that is the case? – Tobias
• Can you outline the landscape of projects that leverage the documentation capabilities that are built in to the Python language? – Tobias
• Can you estimate the overall user base for Read The Docs? – Chris
• Do you have any advice around methods or approaches that can help developers create and maintain effective documentation? – Tobias
• Can you list some projects that you have found to provide the best documentation and what was remarkable about them? – Tobias
• Newcomers to open source are often encouraged to submit improvements to a projects documentation as a way to get started and become involved with the community. Do you have any general advice on how to find and understand undocumented features? – Tobias
• Do you have any statistics on the languages represented among the projects that host their documentation with you? – Tobias
• What are some of the challenges you’ve faced and overcome in maintaining such a large repository of documentation from so many projects? – Chris
• How can our listeners contribute to the project? – Chris

Picks

• Tobias
  • The Man from Uncle
  • Minute Physics



• Chris
  • SigAvdi
  • Black Flags: The Rise of ISIS
  • Veritassium



• Eric
  • Khao Soi
  • Climate Change
  • Gardening & healthy eating – Classic

Keep In Touch

• Twitter
  • @ericholscher
  • @readthedocs
  • @writethedocs

Links

• Stripe docs
• Django Girls Tutorial
• Write The Docs
• Write The Docs Meetup Talk
• Write The Docs Slack Channel

The intro and outro music is from Requiem for a Fish The Freak Fandango Orchestra / CC BY-SA