Eric Holscher - Posted in 2013

2013 Year in Review

2013-12-31T00:00:00+00:00

2013 has been a fantastic year. In 2012, I decided that I would focus more on life than my career. This year has been a larger experiment along those lines. I have done a lot of good work on programming, but I have also taken a lot of time to spend for myself.

January

I quit my job a few weeks into the new year. Ending my employment at Urban Airship after 2 years.

This was to train for the Pacific Crest Trail. The Pacific Crest Trail is a wilderness trail that stretches from Mexico to Canada, across the western United States.

February-March

This was mostly spent buying lots of backpacking gear, and going on a crazy number of hikes. I was trying to average 10 miles walking a day, with 20-30 pounds on my back twice a week. These training hikes were to prepare my body for doing this everyday for 5 months.

During this time we also conceived the first ever Write the Docs Conference. Planning this event also took up a good amount of my time during these couple months.

April

Write the Docs happened on April 8-9, and was fantastic. We gathered over 200 people in Portland to talk docs. We got almost uniformly positive reviews, and it was a really great moment in time for me.

April 15

April 14 is when I flew to San Diego to start my hike on the PCT. April 15 was the official start to my hike.

April-June

Hike, hike hike. See some of the most beautiful places in the United States. Meet amazing people, and do something incredibly difficult and rewarding.

These were the best 2 months of my life.

June 16

Come off the trail with a stress fracture in my left foot. Ending my hike over Kearsage Pass in the High Sierra.

June-August

This was a pretty depressing time. I had to re-enter normal society. This was surprisingly difficult, made harder by the fact that I had to wear a boot on my foot for 6 weeks. After walking for over 2 months everyday, the lack of exercise was really tough mentally. Also not finishing the PCT was really hard, because I had never thought about quitting.

September

I attended XOXO Festival. This is where things really started to turn around.

I decided to focus on improving documentation full time for the foreseeable future, asking for help with this on Gittip. I immediately had a good number of people helping to support me, and it heavily validated and inspired my work going forward.

On the exercise front, I did a good amount of biking. This was to limit the exposure my foot had to re-injury. The main event was a bike ride from Portland-Eugene over 3 days.

October

Participated in the Google Summer of Code Book Sprint. This involved spending a week in Mountain View, helping write a book for an open source project.

This really helped me get a better feel for writing with other people, and the general editorial process.

November

We did a November Blog Post Month with a twist. Instead of the deadline being to publish a post, we submitted them to our group for editing. The main value of this was to get better content, not more. It also allowed us to become better editors, and I now find it much easier to edit my own work.

I also started doing a bunch of hiking again, as I would be leaving Portland at the end of the month for a while. It was great to get back into nature, and rekindle my love of hiking after being off for almost 6 months.

I got to visit Vancouver, which was the last major west coast city I haven’t visited. I really saved the best for last. I quite enjoyed Vancouver. It brings the best parts of all my other favorite west coast cities, and combines them into one place. I can’t wait to go back, and maybe spend a month or two living there.

December

I spend the entire month visiting friends and family on the east coast. It’s a luxury that I have time, and I am glad that I spend so much of it with family. It’s often easy to get caught up in life and not remember those who matter the most to you. Spending time with family is something that I will never regret.

We announced Write the Docs again next year, including a European version. I have also started submitting conference talks to a couple places. I haven’t spoken much in the past few years, and I think I am ready and excited to start again.

I also firmed up my plans to travel to Thailand in January for a couple months.

Conclusion

2013 was a fantastic year for me. It really pushed me to grow as a person, pushing boundaries and exploring the world. I will be continuing these trends in 2014, with a new focus and enthusiasm for my work as well.

Focusing on documentation professionally has given me clarity of purpose. I feel like there is a lot I can accomplish in this realm in 2014, and that it will hopefully be the turning point in creating some kind of documentation community.

Read the Docs 2013 Stats

2013-12-23T10:00:00+00:00

2013 has been a big year for Read the Docs. Our mission is to make documentation hosting easier, with the overall goal of increasing the quality of documentation in the programming world. I believe that we have been doing good work towards that goal, and I want to share some numbers to reflect our progress.

Community

Our community has been great this year. I have been really happy to see a few people submit multiple patches and features. This year, we had:

39 people who committed code
550 commits
271 issues - 218 closed, 53 open

Many thanks to Wraithan in particular, who has taken on a large role in helping maintain the site and servers.

If there is anyone else out there who would like to help with operations, especially outside of US timezones, please let me know.

Page Views

Our growth in page views has always been crazy to me. It was somewhere in mid-2011 that Read the Docs went from a hobby project, into something projects depended on. This growth has never stopped, and today a large number of important projects depend on Read the Docs.

Our stats:

65 Million Page Views
13 Million Unique Visitors

For context, these numbers are similar to what MDN has.

Note

These numbers are actually a bit low. Some themes don’t support default Sphinx template blocks, so we can’t count them in our stats correctly.

I think an image shows this a bit better than words:

Site Stats

Our pageviews are driven mainly by 100 or so high traffic sites. We have a lot of small projects that are up on Read the Docs too that we love.

The stats:

7949 projects
11679 users
1040182 builds

Funding

Our hosting costs are sponsored by Rackspace, which is fantasticly generous of them.

Development on Read the Docs is funded by the community on Gittip. I am very grateful for the support that the community has given the project over the years. It is great validation that people value the service you are providing, even when you give it away for free.

The stats:

$167/wk currently
114 people giving money

Conclusion

2013 has been a great year for Read the Docs. We have made a lot of progress, and I think 2014 will be even better.

We are working on a number of new features to expand the user base, and make the site more approachable. We forward to continuing to improve the documentation ecosystem in the new year.

A Better Javascript Workflow with Django

2013-11-21T20:00:00+00:00

Javascript has always been the bane of my existence as a developer. It was the part of the process of developing that I would dread. On the last project I worked on, I found a very simple change that significantly improved my experience writing Javascript.

Problem: One big file

Historically, Javascript lived in one really large file. If you wanted to break up the file, you had to edit your HTML files to make sure they were in the correct order. This always felt really brittle, so I never actually split up my code into multiple files.

Even if you split things up into different files, you had to reply on implicit import mechanisms. A variable would just magically appear in your file because of the import order of the scripts. This incredibly brittle and unintuitive way of working puts up a high barrier to writing well-factored code.

Solution: node-style requires

Node.js has the concept of require. It works very similarly to Python’s import mechanism.

client.js

var events = require('./lib/events')
events.awesome()

lib/events.js

module.exports = {
        awesome: awesome
}

function awesome() {
        console.log("Do awesome stuff.")
}

The module.exports is similar to Python’s __all__, allowing you to explicitly set your public API.

The require system allows you to factor your code into multiple files. More importantly, this allows for code isolation. I can put logic surrounding setting up event handlers in the events.js file, without having it leak into other sections of the code.

Architecting code in this fashion allowed me to write much better code. It gives you an entry point into the code, where the uppermost logic lives. Then you can dive into each specific file to understand that subsection of code. All the benefits normally associated with an import system come to bare.

As a wise man once said:

Namespaces are one honking great idea – let’s do more of those!

Imports in the browser

It’s great that node has an import system, but that doesn’t help me when I’m writing Javascript for the browser. browserify is a project that allows you to have node-style imports in the browser.

Browserify takes all of your Javascript files with imports, and renders them into one large file you can include in your project. It does this by pointing to a file, which is the top-level entry point into your code. In the example above, client.js would be the entry point.

To use Browserify, simply install it with npm:

npm install browserify -g # -g means globally

Then run browserify on your top-level file:

browserify client.js > bundle.js

Browserify outputs the Javascript to stdout, so you can simply redirect it to a file that will contain your bundled Javascript code. The “bundle” is what you include in your HTML:

<script type="text/javascript" src="bundle.js"></script>

A New Problem

As with all preprocessors, the main issue is the workflow around rendering the code into its final form. There are two general approaches for handling this:

Have a program watch for file changes, rebuilding on change.

Rebuild source files on request.

You can use programs like watchdog and grunt to handle rebuilding of files automatically. The main issue with this is the feedback loop. You can save a file and reload your browser, and you aren’t sure if it’s serving the latest change you made.

I generally prefer having it rebuild the source on request. This works well until you have large files that have to be compiled, where reloading each request introduces significant lag. Luckily for my Javascript projects, they tend towards the smaller side.

Beefy is a project that presents an HTTP server, which autocompiles your Javascript with Browserify. To use beefy you install it:

npm install beefy -g # -g for global install

Django Integration

Beefy also works as a simple HTTP server. It auto-generates your Javascript through Browserify, but also serves normal static media. This means you can point your STATIC_URL at Beefy, and it will just work.

First you have to collect your static media into a single directory:

./manage.py collectstatic

Then, from your STATIC_ROOT you run beefy, pointing at your Browserify entry point:

beefy client.js

You can also pass the bundle you want it to generate with a :. This allows you to point at the same Javascript file in development as in production:

beefy client.js:bundle.js

Beefy should now be serving on port 9966. You can point Django at this for static media by using the setting:

STATIC_URL = 'http://localhost:9966/'

Beefy should now be serving your media properly, and auto-compiling your javascript through Browserify.

Note

You may want to symlink your javascript files from into STATIC_ROOT, if you are doing active development on them.

Conclusion

With this workflow you can now write Javascript with a sane import system, and have it Just Work in development. I hope that it makes the Javascript part of your development a little bit more enjoyable.

Codes of Conduct, an Organizers Perspective

2013-11-11T20:00:00+00:00

I helped organize my first conference last year, Write the Docs. It was a great experience, but was also rather stressful. Organizing things is an interesting exercise in managing fear and risk. There are so many possible outcomes, and this is scary as hell.

As an organizer, I found myself looking for systems to minimize uncertainty. Uncertainty is the breeding ground of fear.

Code of Conduct

We established a Code of Conduct for Write the Docs early on. As the conference came closer, it became really valuable for me as an organizer. It was one aspect of the conference that I didn’t have to worry about.

An event that violates our Code of Conduct might happen, but you can’t remove that possibility from existing. If anything did happen, I felt prepared to deal with it. This was much easier because of this amazing document, which provides an example internal policy to follow.

The Code of Conduct also gave us a leg to stand on if there were any issues. If we had to reprimand or expel someone, they couldn’t claim ignorance of the policy. We mentioned the Code of Conduct on conference signup, on the website, and in the opening address.

Conclusion

Adding a Code of Conduct for your conference will reduce a source of stress as an organizer. If anything happens, you have a playbook ready, and you won’t be caught off guard.

If you need a place to start, the Geek Feminism Wiki has you covered. I hope that you consider adding a Code of Conduct to your next event. It means a lot, and will let you sleep easier at night.

A New Theme for Read the Docs

2013-11-04T10:00:00+00:00

We have been hard at work improving Read the Docs over the past month. A large amount of back end work has been going on, and now we have a brand new documentation theme to showcase it.

We have looked at how people use documentation, and built a beautiful and highly functional new interface for browsing documentation. We created a solution that looks great and works well.

Creation

Dave Snider approached me about a month ago, interested in helping improve the documentation ecosystem. We talked about what could improve the Read the Docs experience for the greatest number of our users, and a new theme seemed like a great place to start.

The New Theme

Full site

The full documentation page is now beautiful and streamlined. We got rid of the visual clutter and integrated a full-project Table of Contents in the sidebar. When you go into a specific page, a page-level contents get embedded in the sidebar as well. This allows you to keep context inside the documentation when you land on a page from a search.

Old

New

Mobile

The new theme really shines on mobile. We provide a beautiful interface for phones and tablets, while staying completely functional.

Using it

There are two ways that you can use this theme on Read the Docs. The first is to simply leave your html_theme variable set to default. This is now the default Read the Docs theme. You can also set RTD_NEW_THEME = True in your project’s conf.py, and we will use our theme when building on Read the Docs no matter what html_theme is set to.

After you change these settings, simply rebuild your docs and the theme should update. More information about the theme can be found on the theme documentation page

If you want to continue using the old theme, simply set RTD_OLD_THEME = True in your conf.py.

Conclusion

This theme is a great addition to the documentation ecosystem. It is highly functional and beautiful, allowing users to easily navigate and find what they need.

We have a few more tricks up our sleeves, but theme is ready to launch today. Over the next few weeks we’ll be adding a bit more functionality to it, which should be even more delightful.

I hope that you enjoy using it. If you have any feedback, please open an issue on GitHub. To follow announcements for Read the Docs, follow us on Twitter.

If you want to support work like this, help fund development on Read the Docs on Gittip.

Google Summer of Code Book Sprint 2013

2013-10-24T10:00:00+00:00

Or how I learned to stop worrying and write a book.

Last week, I flew down to Mountain View, Ca for the Google Summer of Code Book Sprint. It is an event that brings open source projects together to write a book in a week. 20 people and 3 projects produced books over a sunny and well-fed week. Kindly hosted by Google, we spent 5 days hanging out at their campus writing away. The three projects involved were:

OpenMRS - A medical records system used in many developing countries, originally created to help with AIDS in Africa.

BRL-CAD - A CAD program for developing 3D models, one of the first open source projects from the United States Military.

Mallard - An XML based documentation framework, from the Gnome Documentation Team.

I was what they called a “free agent”, someone not involved in a specific project that would help out. Free agents are useful for providing an outside viewpoint to the projects.

Writing a book was an amazing experience. It has always felt out of my reach, but time limiting it to a week (really 3 days), made the goal more approachable. I hope this post will help you conceptualize the process of how we wrote the book, and possibly think about doing it yourself. After this experience I think it is something that anyone can do, as long as you keep the scope small.

You can see the finished book for OpenMRS online.

Monday

Heresy

On Monday, we got together to play some games to break the ice. We were asked to write our most polarizing documentation viewpoints on an index card, and they were read out loud in front of the room. People arranged themselves along a spectrum of agreement and disagreement. Physically arranged themselves, by walking to different corners of the room. Then we presented reasons for our views on the topics mentioned.

Some examples are:

Developers MUST write documentation

WYSIWYG editors are evil

This exercise acted to show how diverse a crowd we had. Some people were developers, some were tech writers, some were students, some were teachers, people ranged all across the spectrum of experience. You learned to respect where people were coming, which might be very different from your background.

Audience and Outcomes

After the ice breakers, we did an exercise where each member of the team was broken into a separate group, and had to write down their views for the book. We were told to have up to 3 audiences in mind, and 3 take aways someone would have from reading the book. This allowed people to flesh out their idea of the book without other members of their team present. The idea behind this exercise was to eliminate the group-think that happens when a group works to shape an idea. It also allowed us free agents to get an idea of what book people were writing, and which we might be able to help out with.

Once we all fleshed out our ideas individually, the groups got back together and talked through what they thought the book should be. This is the stage where free agents chose their team as well, so that they could see the vision for the book.

As a project group, we then chose the audiences and takeaways for the book. This is the part where I joined the OpenMRS group. They were writing an introductory book for developers who wanted to get involved in the project, and I felt I could help out as a developer coming to the project fresh.

We assumed everyone would be new to OpenMRS. We then broke this down into 3 types of things people might be new to:

Developers new to Health IT
Developers new to Open Source
Developers new to Software Development in General

The outcomes we wanted people to come away with were:

Understand how to become a member of the OpenMRS community
Be able to get the OpenMRS environment set up
Feel confident doing development on OpenMRS modules

Tuesday

On Tuesday we got together in the morning to come up with a table of contents based on our audience and outcomes. Having the audience and outcomes written down really helped guide and focus the book. At each step someone could ask “is this really serving our intended audience?” We only had 2 and a half days to actually write, so we needed to aggressively trim the content to something that we could accomplish in that time.

Our table of contents ended up looking like:

Introduction
- Welcome to OpenMRS!
Saving Lives With Software
- The Need for Health IT
- Our Response
- OpenMRS Today
Community
- Working Cooperatively
- Collaboration Tools
Technology
- Architecture
- Data Model
- Development Process
- Get Set Up
Case Study
- Creating your First Module
What’s Next?
- Get Involved
- Get Support
- Developer Checklist

Promotion Plan

We also talked through a plan to release the book into the community. There was an understanding that if you don’t promote the book, the time spent writing it might go to waste. Having a way to build momentum for the project in the community would ensure the book continued to live on after this week.

Our original promotion plan looked like:

Blog post announcing the book on the project blog
Tell developers in the project about it, so they can recommend it to people
Add it to all of our beginner documentation
Talk with existing developers to make sure the information in the book is correct
Add a JIRA project so we can track issues with the book
Add a survey so that we can get feedback on the book
Make sure that updating the book is added to release processes

Compare and Contrast

After coming up with ideas inside our own teams, we sent a member to each other team to hear what they had come up with. We were encouraged to steal their ideas if they had something interesting, and to provide feedback if we saw something missing. This worked really well at removing group think again, and making sure that you didn’t have a huge blind spot in your plans.

Start writing

After lunch on Tuesday, it was time to start writing. This part was referred to as “content production”, there was a specific focus on just getting pen to paper. Editing would come later. We worked until 8 in the evening, and then headed back to the hotel.

Around the pool that evening we spent time hanging out and talking about ideas. In particular I talked to the Mallard team, comparing and contrasting it to Sphinx.

Wednesday

Content production continued Wednesday. The goal was to have a complete book by Wednesday night, and then spend Thursday refining and editing it down.

Thursday

Thursday was spent writing until around lunch, then the afternoon was spent editing. We formed groups of 2 or 3 which looked over a section at a time. Each section had an average of 3 chapters, and you looked to make sure the flow of all the chapters made sense together. We would each read a chapter and then talk over each of the issues that we found.

At 6pm on Thursday we called the books done, and all celebrated.

Friday

On Friday we got together to do a postmortem on the process. We talked again about the promotion plan, assigning items to specific people to make sure they got done.

This was all along the theme of continuing momentum forward. We now had a list of tasks, with people who were responsible for getting them done. This made me feel a lot more confident that our work would live on, and really make a difference in the community.

Take aways

I think the mixing of ideas behind groups was really key to success in this endeavor. Group think is potent, and having someone with an outside perspective come in can really reveal your blind spots.

Along these lines, the evenings hanging out by the pool talking through your work was really important. You can’t sit and write 24/7, and having a place to escape and let you ideas breathe really allows you to form them. I think throughout the week everyone was thinking about their book pretty non-stop, but were weren’t necessarily writing non-stop.

I come away from this experience with a lot of inspiration and perspective. Writing a book is something that anyone can do, with a little help from their friends.

Announcing Grok the Docs

2013-10-08T10:38:00+00:00

Are my docs working?

Are folks getting what they need?

I’ve asked myself these questions a lot. Historically I have put Google Analytics on my doc pages, and called it good. I would browse over the data every once in a while, gleaning basically zero information out of it.

Read the Docs hosts a lot of documentation, and I want to help these folks understand how their docs are being used. So I have been working on a project for the last month called Grok the Docs.

Grok the Docs is a bit different, with the main difference being it embeds the information in the page for you. This is interesting because it adds context to the data. I believe that context is the first step from turning data into information. The main interface to Grok the Docs are keyboard shortcuts within the documentation page. So you can access information about the current page you’re on, while you’re browsing. Check out the Example below to see it in action.

Surfacing analytic data in the page is great for the maintainer and user alike. The maintainer can see what parts of their docs are being heavily used, and which parts aren’t being used as much. Users can see where other people are ending up, which is probably where they want to go too.

This is very much just a tech demo currently. I would love feedback from folks about how I could improve the display of the data. Currently it’s something that you need to enable.

It would be great if you have ideas for other additoinal functionality that could be added. This is very much an experiment currently, so I’d love to hear any thoughts you have. Please email or tweet me if you have feedback or ideas.

Once the code is more baked and solid, the plan is to turn it on for all Read the Docs users. After I do a full rollout across Read the Docs, I’ll consider opening it to other people. The code is currently closed source, and will likely remain so. The idea is that this might become a product that can suppliment my Gittip income. If it fails as a product, I will then open source it. That said, it will always be free for documentation on Read the Docs.

This project was done as part of my ongoing work to improve documentation. If you think this work is important, you should support me on Gittip.

Example

This shows how user might harness this data.

Sphinx Live Preview

2013-10-01T19:00:00+00:00

For a long time, there has been a live preview site for reStructuredText: http://rst.ninjs.org/. It is really fantastic for learning the language. The immediate feedback is really valuable in helping you expirment and see how things work.

I think that this tool would be great for people to have with Sphinx as well. I know a lot of people use Sphinx, and then end up on that page, and random things don’t work because they are extensions to reStructuredText. So, I went ahead and forked the app to support Sphinx.

I present: http://livesphinx.herokuapp.com/.

It is still very much a work in progress. The output should be themed nicely, and support syntax highlighting. If you have any feedback or requests, please tweet or email me.

This project was done as part of my ongoing work to improve documentation. If you think this work is important, you should support me on Gittip.

Writing a Beginners Guide to Documentation

2013-09-30T09:00:00+00:00

A few days ago I started a campaign to improve documentation. Today I have the first results to show from this work.

It started first with a presentation that I presented at PDX Python here in Portland. The talk was very well received, so I decided to write it up.

So, I present A beginners guide to writing documentation. It is still very much a work in progress, so I hope that you can provide feedback. The idea behind the presentation and document is to allow people modify and present it themselves. I am hoping to build documents and presentations for other aspects of documentation as well. If you want to give this presentation, I would love for you to email me.

As I said, this work was done as part of my ongoing work on Documentation. If you think this work is important, you should support me on Gittip.

A letter to an old friend

2013-09-28T01:00:00+00:00

A letter I wrote to an old friend Josh, after I had come home from the PCT. It was sent on August 7th, 2013. It captures my thoughts on the trail pretty well.

Text

Howdy,

Indeed the trail satisfied many parts of the soul. Sadly I hurt my foot and had to end the trail before I reached the end, but I still spent enough time out there to understand some of the lessons it has to teach.

I always like to think back to how life was for me before college. It’s crazy how much of a different person I was going in and coming out. We chiseled away at the possibilities of humanity, and ended up with a pretty good statue at the end.

Being on the trail is the closest that I have had to that feeling in my adult life. You are given the time to think without constraint, and bullshit all day long with amazing people. It feels much like college, in that the friends I’ve made will be life long.

It has changed what I want to do with myself for the foreseeable future, seeking out more situations where the intensity and breadth of the human soul can come to bear. It felt like the most natural thing in the world to slip into walking everyday, and living a simple life.

Simple life with good people, a profound and fundamental way to enjoy the world. It showed me how full of bullshit and tedium the “normal” world can be, and how a reduced subset of choice can really expand your happiness.

The months I spent on the trail were some of the happiest of my life. I will look to hopefully relive them again in a few years, but like many things in life, the first time is likely to be the sweetest. Hopefully I won’t go through life looking backwards, trying to feel it again, and will find solace and peace again.

Coming back to reality has been hard, but Portland is a good place to come back to. I have been surrounding my self with good food, mostly from Farmers Markets. Lots of berries and salads, things you can’t eat on the trail. I am also looking into doing some bike touring, once my foot heals, so that I can still explore. Exploring on bike will be a different experience, but one I think I’ll quite enjoy.

I now also have the experience to go and live in the woods for a week at a time. This freedom opens a lot of possibility for adventure in the future. Having amazing tools, the knowledge , wherewithal, and drive to go out into nature again makes me happy.

May there be many more adventures for us both.

Cheers,

Eric

Eric Holscher - Posted in 2013

2013 Year in Review

January

February-March

April

April 15

April-June

June 16

June-August

September

October

November

December

Conclusion

Read the Docs 2013 Stats

Community

Page Views

Site Stats

Funding

Conclusion

A Better Javascript Workflow with Django

Problem: One big file

Solution: node-style requires

Imports in the browser

A New Problem

Django Integration

Conclusion

Codes of Conduct, an Organizers Perspective

Code of Conduct

Conclusion

A New Theme for Read the Docs

Creation

The New Theme

Full site

Old

New

Flyout

Old

New

Mobile

Using it

Conclusion

Google Summer of Code Book Sprint 2013

Monday

Heresy

Audience and Outcomes

Tuesday

Table of Contents

Promotion Plan

Compare and Contrast

Start writing

Wednesday

Thursday

Friday

Take aways

Announcing Grok the Docs

Example

Sphinx Live Preview

Writing a Beginners Guide to Documentation

A letter to an old friend

Text