Developer documentation is one of those things every team knows is good to put out there for developers working on your platform, but also tends to be one of the last things on the priority list for getting done.  There are various reasons for this:

• Maintaining the site hosting the documentation takes too much time.
• The tools for doing the documentation are meh.
• The code changes over time thus easily making existing documentation stale, and having to go through all pre-existing work and updating it is a pain.
• We’d rather just write code.

However, at Event Espresso, we realize that having good quality documentation directed to developers building on our platform is important because, among other things:

• It helps us think through features and systems we are writing about (if its too hard to explain to others, then maybe its too complex)
• It removes some friction third party developers can experience when learning to work with Event Espresso for the first time.
• It helps give some explanation for “Why we did it this way?” for developers who have trouble grasping some seemingly arcane way we chose to do things in the code.
• It helps developers find easier ways to integrate with and work with Event Espresso as they build their own extensions and custom code for their clients.

When I first threw up developer.eventespresso.com, it was a weekend project that I launched fairly quickly to hopefully get the ball rolling.  So I setup a WordPress site, loaded a few plugins that I thought would help with organizing things and ran with it.  For the most part it’s served our team well, but it really hasn’t helped remove the friction outlined at the beginning of this post.  Plus, as a team, we’ve never really been happy with the utility of actually finding things on this site.  As I perused the list of stuff we still have to document, I realized that long-term, the structure of this site wasn’t viable.

With that in mind I realized we needed something that:

• would have 0 maintenance overhead.  No theme adjustments to make, no website updates to manage etc. etc.   We wanted to be able to just focus on content and not the presentation (save TIME).
• still allowed us to own our data/content and quickly move it around if necessary.
• has EASY versioning so that the documentation developers viewed was always relevant for the current code they were working with.
• has EASY authoring tools so when we wrote this documentation we’d spend less time wrangling with formatting code etc, and can focus on just getting things written and out there.
• has great organization and search capabilities for developers to actually find stuff.
• is not too expensive.
• is EASY for developers to discover.

With that in mind, I started looking for things that might help us accomplish those goals.  I first came across readme.io and was swept in with the beautiful design and easy content management (especially their REST API tools, they rock!).  However, although there is an export utility, I still didn’t like that the exports (although in markdown) were polluted with custom blocks/shortcodes used for their platform.  If we ever had to move our documentation elsewhere, converting it could be a pain and take unnecessary time.

I also thought of using something like Jekyll, but really, although its cool and all, there is still some maintenance overhead involved.

Then in some internal communications, one of our devs (Brent) suggested, “Hey, why don’t we just add a docs folder to our repo and throw all our dev docs in there?”  Eureka.  So freakin’ obvious, but so easily overlooked.  And so I ran with it.

Why is this good for you, the developer working with Event Espresso?

• ALL of our documentation is now easily discoverable and accessible right along with our code in the docs folder (you can view it on github – which parses markdown really nice).
• Our documentation will pretty much always be correct for the branch you view it in.  Going forward, when our dev team writes docs about a new api/feature we introduce/deprecate/update, we can do it IN the branch its introduced.
• Github search is way better than WordPress search.  Plus as a bonus, now when you search through Event Espresso core on github, not only will you get results for code returned, but ALSO docs!  Groovy.
• Have questions as a result of the docs?  Open an issue and link to the doc right there.
• Read the doc and find something incorrect, or something you think could be expanded?  Submit a pull request!  Yeah, you can help the documentation get better (really easily).
• With a lot of the friction to writing documentation removed, its much more likely we’ll get more useful documentation out there for you.

Why is this good for our team?

• ZERO maintenance.  No worrying about presentation of the docs, or wrestling with formatting, keeping plugins up-to-date etc.
• Less struggle with versioning and docs becoming stale.  Now, whenever something changes in a branch we’re working on, we can just update the docs in that branch and when it gets released (merged to master branch) all the docs will be up-to-date.
• Focus on content, rather than formatting etc.  Markdown is ridiculously easy to write with, and github flavoured code styling is a breeze.  Our docs can be written right in our IDE!
• not extra cost (free)

Won’t the docs folder add space to the release package?

No.  Currently we have a build process via our grunt bot that removes folders and files we don’t include in zip builds for releases.  Literally a one-liner to ensure that the new docs folder gets removed from those builds as well.

What’s going to happen to developer.eventespresso.com (and the existing links to documentation)?

We’re still going to keep developer.eventespresso.com up for our developer focused blog.  Having a blog is still useful for timely announcements about changes that we can link to the new static docs.  So if you are currently a subscriber to our blog feed, that’s still going to be an excellent way for you to receive developer focused news about Event Espresso.

As well, the github address for our new documentation home is kind of long.  So developer.eventespresso.com/docs is what we will use to link to it.

Finally, we’ve 301’d all old links to documentation so it points to the new home of that item in our docs folder on github.  This means that if you’ve been using any of those links internally with your teams or on your own sites, they should still work just fine, they’ll just redirect to the new home for that doc.

Wrap Up

I hope this change ends up being as good as I think it will be.  Let us know what you think in the comments.