Eric Holscher on Documentation and Read The Docs

Hello, and welcome to podcast.init,

the podcast about Python and the people who make it great. You can subscribe to our show on iTunes, Stitcher, TuneIn Radio, or add our RSSP to be your podcatcher of choice.

You can also follow us on Twitter or Google plus and please give us feedback.

We can leave a review on iTunes so that other people can find us, send us a tweet, send us an email, leave us a message on Google plus or leave a comment on our show notes.

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 also 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 30, 2015,

and your host, as usual, are Tobias Macey and Chris Patti.

Today, we're interviewing Eric Holscher about documentation

and read the docs. Eric, could you please introduce yourself?

Sure. I've been a Python developer now for about 8 years.

I started out of university,

at the Lawrence Journal World in, Lawrence, Kansas where Django was from and then I moved out to Portland about 5 years ago and had a job at Urban Airship, and then been working on kind of read the docs and documentation related projects for the past 5 years or so. So yeah.

Very cool. So how did you get started with the Python language?

So, yeah, when I was in high school, I learned Perl because that's how you made things on the Internet.

And when I was in college, I was kind of

looking for something else that was, you know, maybe a little more forward looking and similar philosophy and I kind of ended up looking at Python and actually ended up reading kind of the Django documentation,

on a on a Thanksgiving trip in my senior year and it kind of just,

taught me Python. It taught me web development. It taught me just about everything that I needed to know. And from there, yeah, it was kind of the classic, you know, bring you know, come into the Python world through Django

and kind of get involved with both.

Yeah. And Django has always had a

pretty extensive set of documentation

and a really good

introductory section, which they've actually been improving as of late. So

being that this is a show about documentation, it's kind of fitting that that was your intro into Python and the overall ecosystem.

Yeah. Definitely. And I I gave a talk at Django birthday, actually, which is kinda like Django's 10th birthday.

There was a little bit about that, about kind of the the very circular nature of of documentation in the ecosystem, I think, where, you know, people get involved through it and then they really see the value in it and help kind of make it a a community kind of something that community values.

Definitely.

And so as we've alluded to, you're 1 of the people behind the Read the Docs project.

And what was your inspiration for creating that platform, and why is documentation so important in software?

So, yeah, it was really just, you know, the classic kind of scratching an itch.

I had a few open source projects that I had documentation for, and I had just, you know, they were on my personal website and I had just, like, a cron job running every half an hour, you know, pulling down the git branch and, you know, running sphinxes make HTML command and, you know, copying them into a a web directory, and that was kind of the the state of the art at that time.

And it was like, hey. We're we're developers. You know, we have, you know, GitHub. We have webhooks. We have all these kind of tools that have just come out and make a lot of sense in this problem space.

And so that's that was really it was a a the actual creation was done in 48 hours in the Django dash

in 2010,

with, Bobby Grace and Charles Leifer.

And it was really just, like, something we thought we could kind of bite off and, you know, it was, like, a simple enough core of an idea that we could do it in 48 hours and actually, you know, have something functional.

And so it was really just kind of on a whim. We're like, yeah. This is

a the right size project for,

this type of, competition. And

so, yeah, we kind of just created it. I think we got 3rd place,

in the competition,

which I was, you know, I was happy about. Right? That's and I think there was, like, 30 or 40 other people.

So yeah. And then just from there, it's kind of just grown

into something much larger than I ever thought it would be.

And so is the underlying infrastructure for read the docs still a Django project?

It is. Yeah. It's all an open source Django project. It's on the, r t f d, GitHub org,

and it's linked from the footer in know, lots of different places or if you just search for it. But, yeah, it's still a big big Django app.

So what makes read the docs different from other static sources for documentation?

So, I think the cool thing I I mean, so read the docs is predominantly

built on Sphinx.

We also support make docs, which is another kind of Python,

doc generator.

And what we kind of build on top of that is really kind of the, you know, hosting and version control awareness.

So, you know, most most of those tools

just deal with, you know, a a set of files

sitting on a file system, And we actually implement a lot of the logic around, you know, different tags, different branches, you know, URL structures, hosting,

and, like, the updating mechanisms where we automatically run it,

you know, on every commit. So it's kind of the, you know, keeping things up to date in in that kind of deployment story, which is always really hard,

with all software. Right?

And so, really, yeah, we're just kind of building on top of the the tools that deal with the actual files to to really give it

more more functionality.

Yeah. And my understanding is that you also support documentation from other languages than just Python. And so in order to provide that support, do those other languages just need to leverage the Sphinx tool chain?

Or do you also have other,

support for other systems?

Yeah. Correct. So,

Makedocs

doesn't really have any kind of language support. It's just a kind of a markdown,

tool

that just does markdown files. And so we actually have added markdown support to Sphinx. So that's 1 of the big reasons we added Makedocs. And so now if you wanna use markdown, you can use, you know, either tool.

But Sphinx really has, yeah, so much more power where it has kind of the concept of domains,

which then allows you to document, you know, arbitrary sets of software. So there's, like, a Python, a c plus plus, JavaScript, you know, Go, dot net,

a bunch of different domains for different languages that allow you to kind of document those specific, you know, language constructs where, you know, every every programming language or most of them at least has the concept of, like, a class and a function and a method,

but they often have different names. And so it just allows you to have that kind of semantic mapping where it's like, you know, in JavaScript, they're called, you know,

prototype.

In in Python, they're called classes and just allowing you to actually kind of use the proper language specific semantics.

And so that's how Sphinx supports all the different languages that it does.

And have you had anybody give you feedback from other languages about any issues that they've had with using Sphinx because of its being written primarily in Python? Or has it been a pretty easy on ramp for people from languages such as Ruby or Go or any of those others that you mentioned?

Yeah. So so the classic issue is that the auto doc functionality where, you know, you kind of take a piece of code and you pull the documentation strings out dynamically

has been lacking from all the other languages except for Python,

because Sphinx was you know, it's implemented in Python, but it was also

originally built to document Python itself.

So it has it still has, you know, a set of features in the core,

that are specific to Python,

and that's been slowly, you know, going away as Sphinx has become much more of a, you know, tool that's used by all the different language developers.

But that's 1 of the things we're actually working on, kind of in the read the docs world is a project we're calling Sphinx Auto API,

which is the attempt to actually bring that kind of auto documentation

concept to all the other different languages.

So that work was actually funded by Microsoft

because they're using, ReadTheDocs and Sphinx for

their ASP dot NET documentation.

And so they wanted to be able to kind of auto generate, you know, reference documentation

for their dot NET sources.

And so we added, you know, that that mapper that takes, you know, the the platform specific, you know,

metadata

tool. So, you know, like, PHP doc or whatever the tool is that kind of pulls the,

pulls the documentation out of the source code, and we kind of have the mapper that turns that into the proper Sphinx markup.

So that was 1 of the things we built there, and we're hoping to kind of have that be that bridge for other languages to to be better supported in the Sphinx ecosystem.

And the Python community seems to have a stronger focus on well documented projects than some of the other languages that I've used. I'm wondering if you have any theories as to why that is the case.

Yeah. It it's 1 of those things I've always kind of been curious about.

And, you know, part of I know, Jacob Kaplan Moss was 1 of my big influences

around documentation.

And so I think a lot of it comes from the top, you know, the Django core people, the Python core people. There's just kind of that

good

good documentation

at the top, and that really leads to setting a community standard. You know, if the the core language isn't well documented, the chances of the libraries being well documented is pretty low.

But, for example, you know, the Django community,

there's an expectation of documentation

that has kind of Django started, but now the the community has kind of taken. And It was really 1 of our goals with read the docs was to kind of be able to take that Python documentation

culture

and kind of export it to other language communities.

You know? So if we give people really good tools for writing documentation,

it will make it much easier for people to kind of do documentation well. And And so that might be 1 of the other kind of, you know, my pet theories is that, you know, sphinx,

in my opinion, is kind of the best it's certainly the most fleshed out kind of open source documentation tool.

A lot of other language communities, all they have is kind of the the Java doc style, you know, reference

from source code, generation

tooling, and they don't have anything that really supports kind of the the pros.

You know, allow me to, you know, explain what is going on, and then let me show you a reference and,

being able to kind of mix auto generated documentation with, you know, handwritten and edited prose,

that was 1 of the big things that Sphinx did, that I think the Python community does really well.

And so many other people just have, you know, auto generated,

you know, from source code documentation, and that's really kind of the state of the art in those communities.

And even and even then,

they have it, but how much they use it is is

very much up for debate. Right? Like like,

Ruby has Ruby doc, but it's it it's not baked into

the language in the same way that Python's,

even source code level generated documentation

is. So it's used

a lot more sparsely and a lot less often,

in my experience anyway.

So I think it it really is interesting to see how sort of sup you know, really strong support for these kinds of features

at the in sort of the DNA of the language

percolate out through the community

and and really make this kind of thing possible. And you mentioned the enhancements

that Sphinx brings to the table, it's almost

like, you know, it makes me wonder if

if Python had not provided that really sort of great foundation if Sphinx would have ever built on top of it in the way that it did.

Yeah. And I this was so 2 things. I think both Go and Rust

both have really, really good documentation practices. Like, Godoc,

it seems to be the kind of community standard there, and it's used almost everywhere. Even though it is a a very kind of simplistic, you know, generate from source code into, you know, a website,

Just the fact that it's used everywhere means that people are actually are writing those docstrings and, you know, making that tool, worthwhile. And and Rust as well just has really, really, you know, advanced documentation stuff built into the language and Rust doc and all this kind of stuff. So it's cool to see the the next generation really getting this right, and it really kinda makes me happy.

And then kind of the second kind of more meta, I think you you asked for pet theories. This is 1 of my favorites is kind of the comparison around,

continuous integration and, documentation

where or sorry, testing and documentation

where I believe that kind of maybe 5 or 10 years ago,

testing was this thing that developers saw as, like, a net negative where it's like, I write tests, and they never get run. And then they go out of date, and they break. And then the time I spent writing them,

was wasted.

And so I think the continuous integration kind of becoming a standard part of software development really helped

testing turn into a net net, net positive for developers where they write the tests. They get run on every commit.

And then if they break, you know, as long as your culture is to fix them,

then those tests really do have a lot of value in the development process.

And I think that, you know, documentation for a long time, you know, people would write,

you know, poor documentation,

then people wouldn't read it. And so then, you know, write the act of writing documentation was a net negative because you spent time and that time didn't, you know, have commiserate value in return.

And so a lot of our kind of my my world view with read the docs is really how do we increase the the value and, you know, flip that feedback loop around

so that writing documentation

is a net positive for developers.

And I think having a documentation kind of community around a project and the language

is a huge part of that. Right? For for Python developers,

their documentation gets read, and so it's really beneficial for them to write it. But for example, if you're maybe a Ruby developer or a JavaScript developer,

the community isn't in the same way. You know, writing a readme will be valuable, but maybe writing really, you know, good documentation might not be, quite as valuable just because it won't be read by nearly as many people.

And, also,

to your bringing up the

correlation of documentation and testing,

it also has an interesting,

sort of

confluence

in Python with the doc test module as well, being able to actually have your documentation

be

useful beyond just from a human perspective and actually be machine consumable to ensure that your

source code and your documentation are lining up appropriately. And that's another way of verifying when they start to drift apart because that's 1 of the other things that I've noticed a lot of times is that

if the documentation

is

even marginally separated from the actual source code, it's much more likely to get out of date. Whereas I think the way

that Python supports docstrings being part of the actual function body makes it much more likely that you will review it as you are modifying the source code

and thereby actually keep it up to date as opposed to letting it you know, fall out of sync and become essentially useless.

Yeah. Yeah. Definitely. We we always call that kind of the Wiki problem

where, you know, at a lot of companies, you know, documentation is stored in a Wiki and and the act of, you know, having to go into a separate place and update things just means that it never gets done.

And so, yeah, I think having that, you know, as close to the source code as you can possibly get. Yeah, like docstrings are the best, but then in repo, you know, markdown or restructure text,

is, you know, the 2nd best,

in that in that regard. So, yeah, I think that's a huge part of it as well.

Since we've mentioned doctest and sphinx, can you outline the rest of the landscape of projects that leverage the documentation

capabilities that are built into the Python language?

Yeah. I think, you know, doc test is really interesting. And then Sphinx actually has a doc test module built in as well that extends that a little bit,

that lets you kind of do similar style doc test things inside of Sphinx. K. So you can have it so you can, you know

so, in in that use case, it's really being able to test the examples in your documentation,

which is similar to the the docstring use case, but a little bit different.

And then make docs is 1 of the other ones that's really been catching on, and it's much more of a yeah. Just a traditional kind of static site generator.

A few of the other ones are kind of the,

you know, documentation,

reference generators. There's things like epidoc and py doctor.

I think those are all pretty out of date. Epidoc, I know, doesn't support Python 3

in its at least in its parse only mode. I don't know about its

when and how it imports software or when it actually imports the code,

to generate the documentation. But I believe it'll it's only Python 2 and doesn't support Python 3 at all.

And Pydoctors is actually something that's broken out of the twisted,

twisted world, and so they're still kind of turning it into more of a generic tool.

And then I think what? There's PyDoc that actually ships with Python,

but it just generates the most, like like, making your eyes bleed HTML you can imagine.

But, yeah, I don't know if there's a huge amount of other kind of documentation tools. There's things that are kind of downstream like Dash, which is really great.

So Dash kind of is just a generic kind of local,

I think it's OSX only, but there's ports for Windows and Linux

that lets you have kind of offline documentation locally on your machine.

But, yeah, in

in that regard,

those are really the big

big kind of doc things in the Python world. And then maybe I'm, you know, ignoring some important ones and feel free to point out if I am.

Yeah. Well, given the huge number of projects available in the pipeline ecosystem, nobody can expect you to actually keep tabs on all the different libraries that are available for leveraging docstrings.

Yeah. And, I mean, at the end of the day, if you're just generating,

a set of, you know, like, a list of, like, you know, alphabetically sorted list of modules or whatever, you know, there's

not that much innovation those tools can really provide. And I think, you know, the sphinx sphinx's approach of kind of mixing, you know, auto generated and, you know, kind of human written text is is definitely kind of the the proper solution in my mind.

But but, you know, pure API references are really valuable

in terms of just being a reference where if you're an advanced programmer and you already know, you know, what you're doing and you just need to kind of be able to reference things. But in terms of actually learning and understanding,

the software, they're not that great of a tool.

So can you estimate the overall user base for read the docs?

Yeah. So

I was just jumped in a terminal, before the call here so I had kind of up to date numbers and we are I think we're at 26,000

projects.

And with that, we have 37,000

users.

Those are people that are actually you know, have created user accounts.

But, yeah, with ReadTheDocs, the kinda interesting thing, right, is that, you know, we it's a a 1 to many publishing platform in a lot of ways. Like, if you're just a consumer of documentation, you know, most people that use read the docs every day, you know, don't really even have accounts. They just are, you know, reading the the hosted documentation.

And so, you know, the best numbers we have for that is Google Analytics.

And so I think the last

time I looked, we were at,

17,000,000

page views a month.

Yeah. And so that's a little over 4,000,000 unique visitors,

each month,

that are, you know, viewing

documentation,

that's hosted on read the docs.

Wow. That's that's a pretty incredible

scale that you're operating at there.

Yeah. It's kinda kinda mind blowing to me a little bit.

And do you have any sort of

sponsorship

or,

I guess,

donation income to help support the infrastructure necessary

to facilitate that sort of traffic?

Yeah. So Rackspace is incredibly generous, and they actually donate all of our servers.

So, yeah, we're given up to $5,000

a month,

in Rackspace credit,

which is just amazingly, amazingly

great.

And they've they've been supporting the project for for I don't even know. As long as I can really remember, it's been at least 2 or 3 years.

And then we did a

a donation campaign that raised $24,000,

earlier this year, and that was actually to fund 3 months of kind of support and operations work.

Because as as you know,

we're not a standard open source project where, you know, the the source code is not the kind of product

that we're really, you know, giving people. It's really the hosting and the uptime and the operations. Right? Like,

part of being in a in a services business is, you know, it's or infrastructure is, like, you know, the docs can't go down.

You know, I've I've been at, like, the PyCon sprints, and I've done a deployment that accidentally broke our servers. And, you know, it was, like, 5 minutes later, everyone's, like, very angry

at me.

So, really, yeah, the the big cost for us is is support and operations.

And so we do we're about to launch in the next, couple weeks,

kind of a read the docs gold, which is similar to, like, Reddit or Trello, where it's, you know, 10, $15 a month.

That's mostly geared towards kind of individuals,

to support the project.

And then we're also looking at doing some more kind of formal fundraising,

focused at corporations.

So I know the Django project,

just kind of hired their first, you know, fundraiser,

officially.

And I think that, you know, in general, kind of sustainability and and supporting open source,

projects in the long term is is really 1 of the the big outstanding issues in the open source community,

and something I'm, you know, very intimately

involved with, and it's, you know, material to my my livelihood.

So it's something that I I realized we haven't always been great at. You know, I think in general, a lot of open source, you can't even give them money, and read the docs has been pretty bad about this. And so we're really trying to, you know,

think through how to do it responsibly,

but really find a way to make it sustainable. And I think, you know,

at least, you know, pay the people that are pair carrying pagers,

because that is not a fun job and doing it for free for too long definitely will burn you out.

And so that's really, you know, the goal in terms of sustainability is, yeah, operations and then just kind of support of the users. You know, it's like, hey. I lost my password or somebody else took my project name or,

just the kind of things that, you know, have to be done from administrative,

point of view.

Yeah. That's a conversation that's been

repeated a number of times recently of the figuring out how to make open source more sustainable from a financial perspective and trying to convince companies that use open source for

being successful to actually contribute back to the projects that they make use of.

I have a half drafted blog post, and it's something I really

feel that I should be contributing to. And I'm just trying to find exactly what I wanna say because I have I have so many thoughts

that it's it's really hard to kind of

break that down into into the the meat of really what what I can uniquely add to the conversation?

Yeah. There's there's definitely

a general

problem to be wrangled with even beyond open source per se, just in the sense of you're trying to do something for the community,

yet it costs money to keep the lights on, Yet you don't wanna become so obnoxious to your users that they end up resenting the fact that you've, you know,

gone for sponsorship. And that's a balance we've tried to strike with this podcast as well. And, hopefully, we've been successful at it. It's it's definitely something that I, you know,

feel like

I'm more than happy to pitch in for for shared resources. I think it's important

to give people the opportunity to help to be sure.

Yeah. And I I but I at the end of the day, individual contributions are not, you know, not the answer. Like, I I kind of view in a lot of ways, I've started to view ReadTheDocs as a library and libraries are supported with taxes. Because if it was up to people just individually contributing,

they wouldn't get funded. And, really, I view it as something that, like things like read the docs and, you know, infrastructure like PyPI and, you know, Travis and all these things should be

effectively a tax on

the venture capital industry.

And maybe not just venture capital, but, you know, kind of the tech industry as a general in in general and, you know, people hate the tax word.

And, you know, that, obviously, I'm not in marketing. But, in general, yeah, it's a pretty classic tragedy of the commons,

where if people don't have to pay for something and it feels like it will be supported by the community,

it will end up not getting funded,

appropriately. And, yeah, I I think the nonprofit world and lots of other folks have have

dealt with this for a long time and there's certainly a lot of information and

and, you know, there's people that have dealt with this that we should be learning from, and it's really a lot of it, I think, is just raising awareness and,

you know, making it more of a social pressure where it's like, oh, hey, you're a big company. Like, what open source do you support?

You know, as when I interview. Right? Like, if I'm a candidate for a job or, you know, we have to find a way that it can really be leveraged into something that affects,

you know, the material,

like, business that they're doing. So it's like, oh, I couldn't hire this person because we're not supporting open source or things like this is where you'll really start to actually get traction, I think.

Yeah. It's definitely a very interesting debate and 1 that has very, very many different viewpoints and approaches that,

it's definitely will be interesting to see how it pans out over the coming months years as the discussion continues.

Yeah. I just think it's a it's a healthy sign that the discussion is discussion is happening. You know? Like, I think 5 years ago, you know, money was like a a the 3rd rail of open source

Right. In a lot of ways.

And just seeing the conversation happening is a a huge improvement.

Yeah. It's definitely

become much more

visible as open source has continued to gain ground, and so many more open source projects are becoming critical to large businesses.

So do you have any advice around

methods or approaches that could help developers create and maintain effective documentation and make sure that it doesn't go out of date?

Really, I think kind of

there's 1 thing that I think is kind of the baseline that everything else depends on, which is kind of as I mentioned earlier, keeping your documentation,

as close to your source code as possible.

So yeah. You know, putting docstrings and things inside your source files that are appropriate, but there's always gonna be content, you know, like tutorials and support information and stuff that obviously doesn't belong inside of source code, and that should live inside of your meter repository, right, in a docs directory.

And then you just need to, you know, mandate the documentation is updated whenever you change code.

So, basically, implementing

a process around pull requests

that, you know, requires documentation

for new features as well as, you know, updating of documentation for,

you know, features that are currently in the code base.

And that's really I know the Django project has had this forever where, you know, code

code won't be committed without tests and without documentation.

And that's really, I think, just kind of the the baseline

for, you know, making sure and and giving developers kind of the tools

to allow them to make sure their documentation is up to date. You just kind of integrate it into the pull request kind of workflow that everybody's

using, you know, or whatever review process you have for, you know, updating your code.

Beyond that, it's really just, you know, using good tools,

knowing how they work.

You know, I think a lot of people just cargo cult a lot of things.

And so people might not be familiar with that term. But, yeah, they just kind of, you know, it's copy and paste, right, where, you know, people are using sphinx and restructure text or markdown even and really not knowing

what they should be doing and and knowing how the tools can can really help them.

But yeah. I mean and really,

if you're if you're big enough and you can kind of work at a company that has a technical writer or if you're know, an open source project and you can attract people like that.

Hopefully, it's getting easier.

I think, you

know, tech writers for a long time have been, you know,

detached from development of source code, but with, you know, APIs getting prominence and all this kind of stuff, I think they're getting more and more involved with, the actual development of software. So, hopefully, they'll find their way into the open community,

and not get repelled.

But, yeah, I think just

caring about it and and knowing

that you need to update it and you need to care about it when you're writing code is super important. And

so so 1 of the other

methods that I use is kind of documentation driven development,

which is I think,

is really valuable for software

design as well as documentation. So if you sit down before you write a little service or a project and, you know, build out,

an example readme file that has, you know, the basic user facing API,

kind of the design decisions that you're making where it's like, we are implementing this instead of using these 2 or 3 existing libraries because these are our goals and here is, you know, why those things don't, solve them.

And just really kind of being able to think through in writing

why and how that, that software is gonna be used will

make the implementation

much better.

Because I think a lot of people have a habit of just going in and solving a problem in software

and then not thinking about how the API is going to be represented to the end user.

So you end up with software that kind of has this layer in the middle that has to translate how it works internally to how it's used externally.

I think writing documentation

first,

that really thinks through how it will be used by the end user

really makes for better software design and implementation

as well as better documentation

because the software is is, by definition, easier

to explain,

because it's, you know, it was thought through from the beginning.

And so that that's more of a kind of development methodology, but I really do think that, you know, thinking through documentation

and, you know, user experience,

before you create software really does help both in the the internal design as well as the usability,

for the user at the end of it.

Yeah. There's a post I

referenced as in a pick a few episodes ago called blog post driven development. That was about a company where whenever they need to implement the new feature, they'll get together

and hash out a blog post describing the new feature. So essentially they're

writing the post about the release before they actually implement the feature as a way to

drive out design decisions and

the things that people outside of the company are actually going to care about so that they make sure that they're staying focused on the necessary problems that they're solving.

Yeah. Definitely. And I I think that's really a a wise approach. And I I think it's true for for most

disciplines. I know, you know, kind of user experience and all these kind of things. Right? Like, if you don't

think through how something's going to be used and and even, you know, validation, like, there's nothing worse than, you know, writing code that never gets used because nobody needed it. So, you know, really really thinking through that kind of whole, you know, product process,

before you actually sit down to write stuff makes, you know, the documentation, makes the UX, makes the design. You know, it it really makes everything easier kind of getting all of those parts of the organization,

involved or or even just all those parts of your brain if it's just you.

But really thinking through that whole process is incredibly valuable, but it's super non obvious as a developer where your first instinct is just to sit down and, you know, figure out how it works by solving the problem.

Right. And particularly

with the recent emphasis on agile and or TDD methods that, you know, where you

just

list the different features that you need. And so you say okay, I'm just going to pick the

top

item from the backlog and work on it and then go to the next 1.

So you're somewhat discouraged from doing a lot of design work upfront and you're supposed to just drive out the design as you go.

Whereas

that can be beneficial from a perspective of

getting started quickly. It can also be detrimental in terms of, as you said, not thinking through the overall

experience appropriately.

So I think that

there's been so much pushback against the waterfall method that any sense you know, that people have started to see any sort of upfront design work as being a regression back into that

methodology

whereas

it does definitely have a very valuable proposition in terms of how it relates to the end product.

Yeah. Definitely. And, I mean, as as without anything, there's balance. Right? If you're if you're writing something that can, you know, easily be encapsulated in unit tests and is a very logical

thing that that is either yes or no or true or false, you know, then, yeah, you don't need a lot from that. But, yeah, like, the larger the problems and the more kind of interesting they get, the more you get value from kind of having all those different,

you know you don't want the person coming in and telling you that it, you know, can't be done at the end of the process.

Yeah.

So can you list some of the projects that you have found to have the best

documentation and what was most remarkable about the projects and the way that they provided the documentation?

Yeah. So I think 1 of the 1 of the things a lot of people always think a lot about is kind of the design and user experience.

And there's been a few a few different things,

lately that have really,

I think, kind of

shown that this can be done really well. And 1 of them is kind of just like the API documentation

space

has gotten really, really interesting

where, you know, you have a lot of, you know, like, playgrounds where it's you know, here's an example of the API documentation, but now you can click this, and it'll drop you into a little thing that shows you, you know, a live,

you know, live response

of that request. And, you know, people like Stripe will automatically insert your own, you know, development keys into the curl examples or this, you know, stuff like that where it's literally just, you know, copy and paste, and it will, you know, adapt to what you're doing and kind of be relevant to you as the user.

Similarly, you know, I I really like the trend of, you know,

like, having the little language switcher that shows you the examples in the different languages where it's like, you know, here's the Python example if you're a Python person or the JavaScript or the curl or,

so I think there's been a lot of just kind of UX improvements

to make make documentation kind of more functional,

for users.

Beyond that, I think,

really, it is just all about the content and, you know, having people that

understand what their users want. And so, really, the best, you know, the best documentation

is

what was useful for you. So I think, you know, Django is often cited as having really good documentation, but it can be incredibly infuriating,

for 1 user and amazingly perfect for the next. And it's really just, you know, being able to try to provide documentation

that

kind of you can empathize and understand where the user is coming from so they can kind of get what they need out of it.

So, you know, a lot of a lot of people provide API references, which is which is perfect for an incredibly technical library that has, you know, a small surface where it's like, hey. I just need to get in, and I know I need this tool, and I already know the problem, and I just wanna use it. But, you know, things like the Django tutorial where or the Django Girls tutorial

where it's like, hey. I'm just getting started with, you know,

programming and and web development. And so you need to have a much broader view. So I think the Django Girls tutorial does this

amazingly well where they're like, hey. You know, we're gonna teach you Django, but we understand that that's not all we have to teach you. And that was 1 of the 1 of the kind of views

of the Django docs when I first started was, you know, they're teaching me Django, but they're also teaching me good Python practice. They're also teaching me good web development practice.

And so I think that's 1 of the really kind of keys to what I consider kind of good documentation is just knowing that audience. Right? Like, in your tutorial or your your topical guides

being broader and and having that kind of breadth

that allows people to really understand the problem space, to understand

the problems that you're solving.

And then, you know, on your API reference documentation, it should be super to the point and obvious. And,

so I don't I don't have everyone always asks this question, and I think it's a really hard 1 to answer because you can show someone an example that you really enjoy. And a lot of people will just judge it on the design or, you know, they won't really actually understand

the the person coming into it, which is really where you see value in documentation.

But, yeah, I think just kind of understanding

what good content should be and how to separate out the different, you know, parts of your documentation for different users and when they need them

is really, really important to having, you know, kind of good documentation.

Yeah. I'll definitely say that 1 of the things that often stands out to me when I'm reading through a project's documentation

is having

a good organizational structure to it.

So 1 of the things that has definitely become commonplace is the getting started section where it just has a brief overview of this is how you get up and running with the project if that's all you want to do.

And then also having sections for more in-depth treatments of some of the different design decisions or

use cases. And then again, also having the API reference. So

I've definitely

1 of the things I definitely notice when I'm

viewing documentation that has poor organization is that I have a much harder time figuring out what I'm supposed to be doing with it, how I'm supposed to be using it.

And sometimes I'll actually end up just discarding the project entirely if it doesn't have sufficient documentation because I don't have

the time to be digging through the source code to try and analyze what it's actually doing and how and why.

Yeah. And this this is the 1 of my primary frustrations with the, like, directory full of markdown on GitHub approach,

that seems to be that a lot of projects seem to use is is that it gives you no no structure and no kind of

guidance and yeah. You just you're lost in the sea of markdown

and you just yeah. It's like, where do I go? Where should I start? What I'm on this page, but where do I go next? And, you know, all those things that really having, you know, like, a table of contents and, you know, next and previous and, you know, all those kind of things that, you know, a real kind of documentation website give you,

just yeah. To give you that kind of context and that structure and that, you know, confidence that you know where you are and you're you're in the right place and, you know, that kind of stuff, I think, is super important.

Yeah. Even just the next and previous buttons are a huge UX,

benefit because I was actually reading through some documentation earlier today that didn't have those buttons and having to keep scrolling back up to click on the next item in the table of contents, which is kind of frustrating,

particularly after all my experience with browsing through docs on the read the docs site where it does have that capability.

So

newcomers to open source are often encouraged to submit improvements to a project's documentation as a way to get started and become involved with the community. I'm wondering if you have any general advice on how to find and understand some of the undocumented

features or

find

gaps in the documentation

itself for where where that, where those improvements are needed?

Yeah. I think, especially in the open source world, the the beginner

onboarding stuff tends to be the worst,

because the people that tend to write documentation

are the experienced

people. And, you know, it's really hard to kind of maintain that beginner's mindset and really

have that, you know, that empathy with with a person who's just coming. And so it's so so easy to kind of assume knowledge and leave parts out.

And so, yeah, I think for a lot of newcomers really just, like, using the documentation

and getting

going and kind of getting introduced to it and keeping notes around, like, what, you know, what errors did I encounter, what,

what commands did I type that I had to Google, you know, all this kind of stuff where it's, like, what what was the web of knowledge that existed outside of the docs that, you know,

is they thought I knew that I didn't know.

And that's really 1 of the best ways for kind of new people to get involved because they don't have to fake being new

like a a core contributor or something might.

And I I think a lot of projects have started having kind of, like, you know,

newbie friendly or good first bug or, you know, kind of tagging. And I think,

I know Django does this in a number of other projects. You know, having having, you know, documentation issues,

open and kind of tagged in a a beginner friendly way really, you know, kind of solves that problem where where I'm able to kind of identify as a project owner something that needs to be better documented or or is confusing,

but I might not be the best person to actually write it and kind of keeping those open and and giving giving that as a, you know, something for new people coming in as a kind of a little fig leaf, so they have somewhere to start and how to kind of have that first contribution is is much more valuable to a project than me just going in and fixing it,

because that that just kind of cuts off all of the the, you know, ways that new people can come into the project.

This is 1 of those areas where I think Python really shines also with regards to some other languages and communities I've encountered. I can't tell you for the years that I was working in Ruby, predominantly,

how many times I got told, use the source, Luke, which, while it may be good advice,

is,

like, you know, throw me a bone, give me a hint, even, like, you know, which which part of the source. Like, you know, if you have any familiarity with the project yourself,

you know, any any any crumb trail you can leave would be immensely helpful. And if you don't, then just say you don't because

use the source, Luke, is just

not not remarkably helpful.

Yeah. Definitely. It's that's the it's the patches accepted of, you know, helping people.

And so I'm just curious if you have any statistics

on the ratio of languages represented among the projects that host their documentation on read the docs.

Yeah. So I have just kind

of anecdotal,

knowledge in my brain, but we also, I think maybe a year ago, added a a little programming language,

flag,

on the project settings

that'll actually let people say kind of what what the language is. And, you know, unsurprisingly,

Python is is, you know, vastly overrepresented.

I think we had

I wouldn't of course, the the vast majority are are undefined

where here, I think we have, like, 12,000

projects that are just, you know, have never filled that in. Then we have,

35100

that are Python.

And then the next kind of runner-up are,

PHP

and JavaScript.

And then there's a bunch of others, you know, a few Perl. There's some Ruby,

Julia. Because Julia actually hosts their docs on ReadTheDocs.

So their ecosystem has been really,

you know, has it's been kind of an obvious choice for them.

And there's some Java and Go and a few others,

like c c plus plus and, c sharp.

But, yeah, I I'd say, you know, by an order of magnitude, Python is is the most represented.

But then,

especially, PHP has really kind of caught on to it and there's some pretty big PHP projects using it.

And then the, the Microsoft ecosystem has has gotten really interested lately because of our work, you know, with them supporting,

documenting their open source stuff.

But, yeah, in general, it's, you know, still heavily Python, but there's lots of other people kind of getting getting interested in it.

1 of the first times I ever heard about read the docs actually was at,

ChefConf

last year. I was in a training course,

and I was sort of carping about Chef Spec in particular.

The the default doc set for Chef Spec is just not amazing. It's the typical sort of, like, you know, bare bones reference,

and it can be a struggle when you're getting started using it, trying to figure out how to actually sort of apply this stuff.

And someone

1 of the the instructors said,

use the Chef Spec read the docs page.

It's immensely helpful, and and they were right. So it's great

stuff. Oh, cool.

So what are some of the challenges you faced in overcoming maintaining such a large repository of documentation from so many projects?

I think the

the big 1,

in the Python world is the fact that Sphinx depends on

importing code

to generate documentation

using its autodock features.

And so this is something we've been

working to fix for a long time.

But to actually kind of build the documentation for a large set of Python projects, you actually need

a fully kind of working environment,

with that project. So any kind of, you know, import level dependencies, any c libraries, it depends on

for those imports.

You know, this has specifically been a really big issue in the scientific Python world because of their kind of they depend on a lot of c, you know, as you tend to when you have, you know, data problems that are large and you need stuff to go fast.

And so that's something that's really frustrating is the fact that, you know, we need to install, you know, 500 megs of, you know, random

Python code and libraries

in order to kind of generate a a handful of, you know, API references,

for a project.

And so we're really trying to kind of

every other language in, you know, with our auto API work that we're doing is, you know, kind of parse only where it goes in and just kind of looks at the code on disk and pulls pulls out the information,

about the, you know, the doc strings and, you know, the API reference kind of metadata,

without importing the code. And so we're really trying to kind of push the Python world towards that. We haven't we haven't done a huge amount of work there, publicly, but, internally, we're working on stuff to really make that better.

That's really just kind of, yeah, having to have an entire environment to build documentation is I mean, it's bad for the project users as well. Right? Like, everyone who needs to build documentation now needs to have a a completely working installation

of the piece of software,

which oftentimes leads to, you know this is 1 of the cool things about read the docs is it forces you to make your doc your doc builds repeatable.

You know, so many projects, the documentation is generated by someone who just, like, pushes it up to GitHub pages, you know, once a month

and it depends on, you know, some local path on his file system to a config file or

or something like that.

And so, actually, making it so there's, you know, a specified repeatable build process

is 1 of the kind of unexpected outcomes of of having read the docs around.

But, yeah, I think in general,

like, scaling has been relatively simple

because we it's all statically generated. So, you know, we're just serving lots of HTML files.

We do

at some point, because of the environment issues, we do have backups,

just because, you know, there's 20 people, like, at PyCon sprints or something.

There's a bunch of people trying to, you know, generate their documentation at once, and we have a a limited number of, you know, documentation build servers that can only do so much.

So

but in in that regard, you know, having

lots of projects

other than, you know, kind of traditional, you know, name spacing issues and,

stuff like that,

it hasn't really the the scale hasn't been a huge issue

except for, you know, just traditional, you know, we need bigger servers and we need

more disk space and that kind of stuff.

Very cool. So how can our listeners contribute to the project?

So 1 of the big ones would be just to help with the development.

You know, it is a a open source Python and Django app. For the the amount of people that use ReadTheDocs, we get a surprising

surprisingly few,

number of contributors.

The people I've talked to, a lot of that is because, you know, they fall into, like, 1 or 2 camps. 1 is, like, it already does what I need. And so there's really I I don't have any motivation,

to fix something or or work on it. And the other camp is just people that kind of view it as a service and not as an open source project.

So, you know, when something breaks, they just, like,

open an issue instead of thinking that, you know, like, I'm gonna write a test case or, you know, I can I can solve this with with code? They're just like, oh, no. It's broken, and so this is your problem because it's like a website.

And so, yeah, I think for a lot of people, you know, just contributing, you know, either code or,

just being active on the GitHub issue tracker and, you know, helping triage.

Recently, with that kind of 3 month thing we did, we implemented a fully standard kind of,

triage process and, you know, we have a whole, you know, a bunch of documentation about how people can contribute.

And, yeah, it's it's pretty comprehensive at this point

in at least around kind of dealing with tickets and dealing with kind of the code

and how we kind of do pull requests and that kind of stuff.

So, yeah, you know, if people wanna file a pull request or, you know, if there's stuff that's not documented, you can, of course, always contribute to our docs. They're, you know, just in the repo

for with everything else.

And then yeah. The other big 1 is if you, you know, have a company and you are looking for kind of ways to contribute to the community,

we are looking at, you know, sponsorship on the corporate level.

And we're we're gonna launch kind of the the individual

level kind of contributions here soon.

But, you know, really, we want corporations to be supporting us and, you know, that's where, you know, the majority of the money should be coming from, and it's where the majority of the money in the ecosystem is.

So if people could talk to their employers and really kind of, you know, agitate for, you know, supporting these these infrastructure services they use every day,

that would be another huge huge win.

So before we move to the picks, are there any questions that we didn't ask that you think we should have or anything that you wanna bring up?

Yeah. I think just like the other kind of this has been focused mostly on read the docs. But 1 of the other really kinda cool and exciting things that I've been working on lately is write the docs,

which is kind of our our, you know, overarching documentation

community.

So this actually, you know, as the name suggests, it kind of spawned and the idea was to have kind of a a read the docs community conference.

But then we we kind of announced it and we found this whole kind of different group of people. And so Read the Docs is actually

a very small part of Write the Docs, you know, mostly just in my involvement and kind of helping organize it. But it's this really awesome group of, you know, technical writers,

developers, people that work in support,

designers, you know, managers, product people, really, like, a whole kind of

really interesting kind of diverse mix of people that care about documentation in software.

And so it's in Portland. It's actually the week before PyCon.

We've been in May in Portland for the past 4 3 years, so this will be our 4th. And Python kinda came in and and moved in on on our dates.

But so it's it's the Monday Tuesday before,

and then PyCon is the following Monday Tuesday after that. So it's a little it's it's annoyingly spaced for people to come to both. But if you wanna come and hang out in Portland, I'm based here as well, so I can I can show you a good time?

Yeah. And it's it's a really fun group. There's,

I think we have meetups in 15 cities across,

the US and Europe,

And then we do a European conference as well, that'll be in its 3rd year, and we're still deciding where, but it's been in Budapest and Prague, the previous 2 years.

So yeah. So it's just this really kind of cool group of of people that, you know,

span kind of all different kinds of, job titles and backgrounds. And,

it's beautiful because it's kind of has gender diversity built in.

Because, basically, the whole thing's been 5050

in speakers and everything from the start, just

kind of as a an artifact of it not being a development kind of specific conference. And so it's been really exciting and and fun to have kind of this real kind of diverse and interesting community of people.

And we didn't really have to try. Like, we just have to not screw it up.

And it's it's really a a really great group. And so I definitely if it if documentation is something you're interested in, even if you don't care about sphinx to read the docs, you know, it's it's

definitely worth being involved with,

you know, regardless of your where where in the documentation world you you live.

And you mentioned that part of the write the docs,

project is meetups, and I'm wondering if you have any sort of media kit or other starting resources for anybody who wants to create their own local meetup that is part of that overarching

organization.

So, yeah, we had a we had a talk at the conference last year about starting a meetup.

And so, yeah, it was the guy who, actually organizes the meetup here in Portland. He gave a a 15 minute talk on, you know, everything you need to think about and everything you need to, need to do. And so that's really kind of where we point people as a starting point. We have a little bit of documentation,

around that kind of internally, but nothing, you know, formally published.

And then we do have a a Slack channel for our community that I think has, like, a 150 or so people.

Maybe 200.

And,

there's a kind of a meetup organizers channel.

So all of the different people that organize meetups for all the different cities can kind of hang out. And so they're they're a great kind of repository of information

of, you know, hey. I have a question, or how do you find a venue or, you know, all these kind of things. And so that's kind of how we've been helping

onboard and bring those up.

Excellent. So if there isn't anything else, then we can go ahead and move to the picks.

Yeah. I think I think I'm good.

So for my first pick today, I'm going to choose a movie that I watched recently called The Man From UNCLE,

which is a modern

remake of a TV show by the same name from the sixties.

And it was a very well done movie. It's a sort of a spy intrigue movie, but it has a really good mix of action and humor

and character development.

And all of the main characters play off each other really well with some phenomenal acting. So Definitely recommend checking that 1 out.

For my next pick I'm going to choose a YouTube channel called Minute Physics.

And it's a bunch

of YouTube episodes

that usually run-in the range of about 5 minutes long. And they all have to do with

different aspects of physics

and tangentially some of the related science. So definitely an interesting 1 to check out.

And I will leave it at that this time around. And go ahead, Chris.

Hey. Thanks, Tobias. So,

my first pick is,

kind of an odd 1 in the sense that it's actually a newsletter.

It's by, a man named Avdi Grim, who is a a bright light in the Ruby community.

I know this is a Python podcast, but, you know, whether any Pythonist is or are particularly willing to admit it or not, Python and Ruby do share quite a number of similarities,

and so I think it behooves

all of us in both communities to sort of keep track of what's going on in the other. And

Abdi has started a newsletter,

an email newsletter

with just a whole bunch of

really cool so he's just a very deeply thoughtful person, and it and it had contains,

links and commentary and musings and quotes from our industry,

different things that he's read recently that he likes.

It's just it's really great stuff. If you're technical

and you like to sort of cast a wide net over,

resources that you want to be able to delve into to improve yourself as a programmer,

I highly recommend

it. My next pick is a book.

After the Paris attacks

of a couple of weeks ago, I know I personally felt like I really wanted to sort of get behind the headlines

and try to understand

what's going on,

in the Middle East with ISIS a bit more. So I I read this I'm reading this book, called Black Flags, the Rise of ISIS,

And it's really it's a really fascinating look sort of behind the headlines that focuses on

a number of individuals and and particular geographic areas.

And so far, I'm about halfway through, it's been incredibly insightful and really sort of a view into,

you know, the circumstances

and people that have have made

this this

situation what it is today.

My next pick is a YouTube channel. This kind of pairs well with Tobias' pick of MinutePhysics.

Although this isn't physics specific per se, this 1 is a YouTube channel called

Veritasium,

a science teacher

who essentially

does these videos on various topics in science. They can range from

physics to astronomy

to, you know, whatever.

And they're just really, really interesting. Like, he did a recent episode on

nihilism,

on on sort of on-site

in the ruins of Chernobyl.

So it's it's really good good stuff. It's an ex a fine example of, in my opinion, some of the best television out there these days is on YouTube and for free.

Eric, please, give us any pics you may have.

Yeah. So 1 of my my current obsessions is a,

Thai noodle dish called khao soi,

which is just this amazing

dish. I spent some time in Northern Thailand around Chiang Mai, couple years ago and really fell in love with it where, you know, cost a dollar and you could buy it from lots of vendors on the street.

Been trying to to slowly recreate it,

with various, you know, Asian markets and that kind of stuff. And, definitely, if people are into the kind of spicy, interesting

kind of Thai food,

Find it at a local you know, a lot of you know, it's not your standard kind of pad Thai or,

those kind of things, but a lot of Thai restaurants will have it and it's amazing.

And then

I just saw, Brett Vicker

who just does this amazing work on kind of modeling,

data and information. Just basically all of his work is really worth looking into.

But he just published something the other day about kind of climate change

and how we as technologists

can,

you know, help influence it. Right? Because it's this

global problem that's really nebulous and and hard to kind of really think about. And it's this beautiful,

piece where he kind of goes through, you know, like, the problem, the different angles, and it's incredibly

well researched and has beautiful, you know, visualizations

as is kind of his trademark. And it really kind of woke up my kind of inner, like, okay. Like,

even though I'm just, like, a person who makes things on the Internet, there's a lot that can be done that I have the skills,

to create. You know, he talks about, you know, building different tooling for, you know, energy modeling and and giving people, you know, better you know, the equivalent of, like, IDEs

for, you know, thinking about

energy and and solar and all these kind of things and just all sorts of different kind of angles and

things around that problem.

That was kind of the best best explanation of the problem space as well as kind of being something that hit me close to home being, you know, here's how you can also affect change,

in our industry.

And then 1 of the other ones I've just been thinking a lot more about is kind of eating and, you know, this

this classic, you know, oh, did everything is bad for you that was good for you that

is kind of our our journalism around food and, this Michael Pollan piece of, you know, it's he's he's kind of the classic guy who'd said, you know, eat food, not too much, mostly plants.

And this is his kind of just article on,

that I reread the other day on just kind

of why

food culture and all this kind of stuff is kind of broken and processed foods are a bad thing and just really about how to think about eating

in a way that's kind of consistent with history and not just what, you know,

some crappy science

experiment said 5 years ago.

And so, yeah, just trying to think more about, you know, gardening and and eating and having food be a a communal part of life that takes time and costs money and is something that that I care about, not, you know, the soylent generation of

I just need nutrients and it doesn't matter what form they come in.

And I think that was really kind of interesting. You know, it it relates to the climate change stuff, but is just as well around being, you know, healthy and and how to, you know, handle a very large part of, you know, our lives, which is, you know, eating and consuming food. So

that that is my those are my picks.

Excellent.

I'd like to second Chris' pick of Sig Avdi. It's I've subscribed to that and I've been enjoying his newsletter, so definitely worth checking out. And I'd also like to second Eric's pick of khao soi, and it's definitely delicious.

So if you like Thai food at all, certainly try to find some.

So for anybody who would like to keep in touch with you and follow what you're up to and what's going on with read the docs or write the docs, what would be the best ways for them to do that?

Twitter is likely the, the best. I'm air culture on Twitter and then read the docs and write the docs both have accounts,

of each of their names.

And so, yeah, they I try not to cross too many of the streams even though they're very very similar in nature.

Yeah. If you care about the community and that kind of stuff, write the docs is great. We just announced our dates,

for the conference this year and, you know, all the information about that will be posted to Twitter.

Yeah.

Excellent.

Well, we really appreciate you taking the time out of your day to join us and talk about documentation

and read the docs.

And, yeah, it was a lot of fun, and I'm sure our audience will enjoy it.

Thanks so much for having me. And, yeah, it was super fun. Thanks for putting the time in and doing a podcast. I know it takes a lot of work, and we definitely appreciate it. Well, we enjoyed doing

it. It is a lot of fun.

Alright. Cool. Thank you. Have a good night.

The Python Podcast.init

Summary

Brief Introduction

Interview with Eric Holscher

Picks

Keep In Touch

Links

The Python Podcast.__init__