December 20, 2015

Eric Holscher on Documentation and Read The Docs

1 hour 5 minutes

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

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

...more

View all episodes

By Tobias Macey

4.4

100100 ratings