Date: Sun, 20 Dec 2015 11:00:00 -0500
<p>Visit our <a href="http://pythonpodcast.com?utm_source=rss&utm_medium=rss">site</a> to listen to past episodes, support the show, and sign up for our mailing list.</p> <h3>Summary</h3> <p>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 <a href="https://readthedocs.org/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Read The Docs</a>, about why documentation is important and how we can all work to make it better.</p> <h3>Brief Introduction</h3> <ul> <li>Hello and welcome to Podcast.__init__, the podcast about Python and the people who make it great.</li> <li>Subscribe on <a href="https://itunes.apple.com/us/podcast/podcast.-init/id981834425?mt=2&uo=6&at=&ct=&utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">iTunes</a>, <a href="http://www.stitcher.com/s?fid=64838&refid=stpr&utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Stitcher</a>, <a href="http://tunein.com/embed/follow/p726240/#?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">TuneIn</a> or <a href="https://www.pythonpodcast.com/feed/mp3/?utm_source=rss&utm_medium=rss">RSS</a></li> <li>Follow us on <a href="https://twitter.com/Podcast__init__?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Twitter</a> or <a href="https://plus.google.com/+Podcastinit-the-python-podcast?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Google+</a></li> <li>Give us feedback! Leave a review on <a href="https://itunes.apple.com/us/podcast/podcast.-init/id981834425?mt=2&uo=6&at=&ct=&utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">iTunes</a>, <a href="https://twitter.com/Podcast__init__?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Tweet</a> to us, send us an <a href="mailto:hosts@podcastinit.com">email</a> or leave us a message on <a href="https://plus.google.com/+Podcastinit-the-python-podcast?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Google+</a></li> <li>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 <a href="http://pythonpodcast.com?utm_source=rss&utm_medium=rss">pythonpodcast.com</a></li> <li>I would also like to thank Hired, a job marketplace for developers, for sponsoring this episode of Podcast.__init__. Use the link <a href="http://hired.com/podcastinit?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">hired.com/podcastinit</a> to double your signing bonus.</li> <li>Linode is sponsoring us this week. Check them out at <a href="http://linode.com/podcastinit?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">linode.com/podcastinit</a> and get a $10 credit to try out their fast and reliable Linux virtual servers for your next project</li> <li>We are recording today on November 30th, 2015 and your hosts as usual are Tobias Macey and Chris Patti</li> <li>Today we are interviewing Eric Holscher about Documentation</li> </ul> <div class="well"><a href="http://linode.com/podcastinit?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank"><img alt="Linode Sponsor Banner" src="https://i0.wp.com/podcastinit.podbean.com/mf/web/tdegpr/linode-banner-sponsor-large.png?w=1200&utm_source=rss&utm_medium=rss" /></a>Use the promo code <strong>podcastinit10</strong> to get a $10 credit when you sign up!</p> </div> <div class="well"><a href="https://hired.com/?utm_content=shownotes-4k&utm_medium=podcast&utm_source=podcastinit&utm_source=rss&utm_medium=rss" rel="noopener" target="_blank"><img alt="Hired Logo" src="https://i0.wp.com/podcastinit.podbean.com/mf/web/ehi957/hired-logo-dark-padding.png?w=1200&utm_source=rss&utm_medium=rss" style="float: left; margin-right: 20px;" /></a>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 <a href="https://hired.com/?utm_content=shownotes-4k&utm_medium=podcast&utm_source=podcastinit&utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">special link</a> 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.</p> </div> <h3 style="clear: both;">Interview with Eric Holscher</h3> <ul> <li>Introductions</li> <li>How did you get introduced to Python? – Chris</li> <li>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</li> <li>What makes Read The Docs different from other static sources for documentation? – Chris</li> <li>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</li> <li>Can you outline the landscape of projects that leverage the documentation capabilities that are built in to the Python language? – Tobias</li> <li>Can you estimate the overall user base for Read The Docs? – Chris</li> <li>Do you have any advice around methods or approaches that can help developers create and maintain effective documentation? – Tobias</li> <li>Can you list some projects that you have found to provide the best documentation and what was remarkable about them? – Tobias</li> <li>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</li> <li>Do you have any statistics on the languages represented among the projects that host their documentation with you? – Tobias</li> <li>What are some of the challenges you’ve faced and overcome in maintaining such a large repository of documentation from so many projects? – Chris</li> <li>How can our listeners contribute to the project? – Chris</li> </ul> <h3>Picks</h3> <ul> <li>Tobias <ul> <li><a href="http://amzn.to/1S27VZp?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">The Man from Uncle</a></li> <li><a href="https://www.youtube.com/user/minutephysics?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Minute Physics</a></li> </ul> </li> <li>Chris <ul> <li><a href="http://devblog.avdi.org/newsletter/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">SigAvdi</a></li> <li><a href="http://amzn.to/1S27PRg?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Black Flags: The Rise of ISIS</a></li> <li><a href="https://www.youtube.com/user/1veritasium?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Veritassium</a></li> </ul> </li> <li>Eric <ul> <li><a href="https://en.wikipedia.org/wiki/Khao_soi?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Khao Soi</a></li> <li><a href="http://worrydream.com/ClimateChange/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Climate Change</a></li> <li><a href="http://michaelpollan.com/articles-archive/unhappy-meals/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Gardening & healthy eating – Classic</a></li> </ul> </li> </ul> <h3>Keep In Touch</h3> <ul> <li>Twitter <ul> <li><a href="https://twitter.com/ericholscher?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">@ericholscher</a></li> <li><a href="https://twitter.com/readthedocs?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">@readthedocs</a></li> <li><a href="https://twitter.com/writethedocs?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">@writethedocs</a></li> </ul> </li> </ul> <h3>Links</h3> <ul> <li><a href="https://stripe.com/docs/api#intro?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Stripe docs</a></li> <li><a href="http://tutorial.djangogirls.org/en/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Django Girls Tutorial</a></li> <li><a href="http://conf.writethedocs.org/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Write The Docs</a></li> <li><a href="https://www.youtube.com/watch?v=ZwQ8Kd48d0w&utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Write The Docs Meetup Talk</a></li> <li><a href="http://slack.writethedocs.org/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">Write The Docs Slack Channel</a></li> </ul> <p>The intro and outro music is from Requiem for a Fish <a href="http://freemusicarchive.org/music/The_Freak_Fandango_Orchestra/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">The Freak Fandango Orchestra</a> / <a href="http://creativecommons.org/licenses/by-sa/3.0/?utm_source=rss&utm_medium=rss" rel="noopener" target="_blank">CC BY-SA</a><img alt="" height="0" src="https://analytics.boundlessnotions.com/piwik.php?idsite=1&rec=1&url=https%3A%2F%2Fwww.pythonpodcast.com%2Fepisode-36-eric-holscher-on-documentation-and-read-the-docs%2F&action_name=Eric+Holscher+on+Documentation+and+Read+The+Docs+-+Episode+36&urlref=https%3A%2F%2Fwww.pythonpodcast.com%2Ffeed%2F&utm_source=rss&utm_medium=rss" style="border: 0; width: 0; height: 0;" width="0" /></p>