Write the Docs, Proper Portland Brew, Hack n’ Bike and Polyglot Conference 2013

Blog Entry Index:

I just wrapped up a long weekend of staycation. Monday kicked off Write the Docs this week and today, Tuesday, I’m getting back into the saddle.

Write the Docs

The Write the Docs Conference this week, a two day affair, has kicked off an expanding community around document creation. This conference is about what documentation is, how we create documentation as technical writers, writers, coders and others in the field.

Not only is it about those things it is about how people interact and why documentation is needed in projects. This is one of the things I find interesting, as it seems obvious, but is entirely not obvious because of the battle between good documentation, bad documentation or a complete lack of documentation. The later being the worse situation.

The Bloody War of Documentation!

At this conference it has been identified that the ideal documentation scenario is that building it starts before any software is even built. I do and don’t agree with this, because I know we must avoid BDUF (Big Design Up Front). But we must take this idea, of documentation first, in the appropriate context of how we’re speaking about documentation at the conference. Just as tests & behaviors identified up front, before the creation of the actual implementation is vital to solid, reliable, consistent, testable & high quality production software, good documentation is absolutely necessary.

There are some situations, the exceptions, such as with agencies that create software, in which the software is throwaway. I’m not and don’t think much of the conference is about those types of systems. What we’ve been speaking about at the conference is the systems, or ecosystems, in which software is built, maintained and used for many years. We’re talking about the APIs that are built and then used by dozens, hundreds or thousands of people. Think of Facebook, Github and Twitter. All of these have APIs that thousands upon thousands use everyday. They’re successful in large part, extremely so, because of stellar documentation. In the case of Facebook, there’s some love and hate to go around because they’ve gone between good documentation and bad documentation. However whenever it has been reliable, developers move forward with these APIs and have built billion dollar empires that employ hundreds of people and benefit thousands of people beyond that.

As developers that have been speaking at the conference, and developers in the audience, and this developer too all tend to agree, build that README file before you build a single other thing within the project. Keep that README updated, keep it marked up and easy to read, and make sure people know what your intent is as best you can. Simply put, document!

You might also have snarkily asked, does Write the Docs have docs,why yes, it does:

http://docs.writethedocs.org/ <- Give em’ a read, they’re solid docs.

Portland Proper Brew

Today while using my iPhone, catching up on news & events over the time I had my staycation I took a photo. On that photo I used Stitch to put together some arrows. Kind of a Portland Proper Brew (PPB) with documentation. (see what I did there!) It exemplifies a great way to start the day.

Everyday I bike (or ride the train or bus) in to downtown Porltand anywhere from 5-9 kilometers and swing into Barista on 3rd. Barista is one of the finest coffee shops, in Portland & the world. If you don’t believe me, drag your butt up here and check it out. Absolutely stellar baristas, the best coffee (Coava, Ritual, Sightglass, Stumptown & others), and pretty sweet digs to get going in the morning.

I’ll have more information on a new project I’ve kicked off. Right now it’s called Bike n’ Hack, which will be a scavenger style code hacking & bicycle riding urban awesome game. If you’re interested in hearing more about this, the project, the game & how everything will work be sure to contact me via twitter @adron or jump into the bike n’ hack github organization and the team will be adding more information about who, what, where, when and why this project is going to be a blast!

Polyglot Conference & the Zombie Apocalypse

I’ll be teaching a tutorial, “Introduction to Distributed Databases” at Polyglot Conference in Vancouver in May!  So it has begun & I’m here for you! Come and check out how to get a Riak deployment running in your survival bunker’s data center. Zombies or just your pointy hair boss scenarios of apocalypse we’ll discuss how consistent hashing, hinted handoff and gossipping can help your systems survive infestations! Here’s a basic outline of what I’ll cover…

Introducing Riak, a database designed to survive the Zombie Plague. Riak Architecture & 5 Minute History of Riak & Zombies.

Architecture deep dive:

  • Consistent Hashing, managing to track changes when your kill zone is littered with Zombies.
  • Intelligent Replication, managing your data against each of your bunkers.
  • Data Re-distribution, sometimes they overtake a bunker, how your data is re-distributed.
  • Short Erlang Introduction, a language fit for managing post-civil society.
  • Getting Erlang

Installing Riak on…

  • Ubuntu, RHEL & the Linux Variety.
  • OS-X, the only user centered computers to survive the apocolypse.
  • From source, maintained and modernized for humanities survival.
  • Upgrading Riak, when a bunker is retaken from the zomibes, it’s time to update your Riak.
  • Setting up

Devrel – A developer’s machine w/ Riak – how to manage without zombie bunkers.

  • 5 nodes, a basic cluster
  • Operating Riak
  • Starting, stopping, and restarting
  • Scaling up & out
  • Managing uptime & data integrity
  • Accessing & writing data

Polyglot client libraries

  • JavaScript/Node.js & Erlang for the zombie curing mad scientists.
  • C#/.NET & Java for the zombie creating corporations.
  • Others, for those trying to just survive the zombie apocolypse.

If you haven’t registered for the Polyglot Conference yet, get registered ASAP as it could sell out!

Some of the other tutorials that are happening, that I wish I could clone myself for…

That’s it for updates right now, more code & news later. Cheers!

Lists of Lists of Lists: Conferences

RICON 2012
RICON 2012

This is the first in a series (AKA a list) of lists that I’m researching and putting together. I’ve had many questions in the last few weeks for “cool conferences”, “awesome hackathons”, “meetups” and “conferences that are worth the time” and related. So here’s the conferences list so far, I’ll be adding more on my conferences page over time. If you’re looking for the most updated list, check out that page. Here’s what others & I have collected so far. Thanks to everyone on twitter, facebook and those other places we’ve discussed conferences:

Github: @adron
Github: @adron

Developer Conferences

  • OSCON
  • Qcon London
  • Qcon San Francisco
  • HTML 5 Developers Conference
  • Web 2.0
  • Velocity Conf Beijing
  • Velocity Conf Santa Clara
  • Strata Conf Santa Clara
  • Strata Conf London
  • Strata Conf Boston
  • Strata + Hadoop World (NYC)

    OSCON (Red Hat table)
    OSCON (Red Hat table)
  • Fluent Conf (San Francisco, CA)
  • Portland Code Camp
  • Seattle Code Camp
  • San Francisco Code Camp
  • Node Conf
  • Node Summit
  • Node PDX
  • Ruby on Rails Conf
  • Cascadia Ruby Conf
  • Strangeloop
  • Defrag / Glue
  • Mobile Web Development Conference
  • Mozilla Festival

    Checking out awesome new tech with Dave McCrory at VMworld
    Checking out awesome new tech with Dave McCrory at VMworld
  • RubyWorld Conference
  • Software Craftsmanship
  • Øredev
  • Monktoberfest
  • RICON
  • Symposium on OS Design and Implementation (OSDI)
  • USENIX Conference on File and Storage Technologies (FAST)
  • High Performance Transaction Systems (HPTS)
  • ACM Symposium on OS Principles (SOSP)
  • BUILD 2012
  • Railsberry
  • Mix12 – Microsoft
  • RealtimeConf
  • Azure Conf
  • DeployCon
  • AWS re: Invent
  • Cloudbeat
  • Structure
  • CloudConnect
  • TacoConf

To add to this list, check out the Google Docs Worksheet I’ve setup or check out the conferences page. The later I will update regularly whenever there are updates to the Google Docs Spreadsheet.

I don’t often ask for RT, tumblr, reddit or other links, but would love to see how big the list can become, so if you have a second please link it, retweet it, like it on facebook or Google+ and get it out there. Thanks!

Updated on Wednesday the 7th of November, 1:37pm 2012
Last Updated 4:41pm on Wednesday the 7th, November of 2012. For the most up to date list check out the conferences page.

3 Things Companies Do Wrong by Developers, The New King Makers

I’m sitting on the train heading from Seattle to Portland today. I live in Portland, but spend a significant amount of time in the beautiful Emerald City. The time on the train is immensely useful to think about concepts, thoughts, introspect, code and generally be uninterrupted in focus. All the while it makes the 3 plus hour trip productive for me. I don’t waste a single minute fidgeting about uselessly in a car. It’s win, win, win and win on all accounts. But enough about the trip and these pleasantries, I’ve got some ranting to do! I want to tell you what is being doen wrong in business, in software and in general in the community around software developers.

1. Stop Listening to PR (Public Relations) when speaking to Developer Communities

PR can serve an important purpose for certain things, but if you’re speaking through PR to the software developers’ community you’ve screwed up. You’ve screwed up big time. I’ll step into dangerous waters and say it is often a good idea to either get advocates (or evangelists) or marketers to speak to developers but the second PR is involved – you’re going to be dead in the water.

In the case of marketing & advocates, they need to know where and how to interact well with the developer community. Developers can smell crappy marketing lines a thousand miles away, so when delivering messaging to the community, it needs to be on point, informative, without the buzz word bingo. Take for instance this gem I heard recently:

Vertically integrated incentivized synergies.

A simple response to that is, “WTF, unfollow, unsubscribe, get outta here.

Conversations have to be real and honest, if there isn’t any experience, skills or knowledge in the marketing or advocacy team, it’s best to own up to that ASAP and ask the community what information they’d like to receive from X company.

Let’s take a few great examples – and yes, I’m going to outline real companies doing things right. I’m not going to harp on companies doing things wrong, because the developer community knows painfully well who these companies are. Those companies can consider this a PSA.

New Relic

Full disclosure, I provide consulting, development how-to & blog entries as a consultant.

New Relic takes several avenues in messages to developers. They’re really good at this and it shows in their honesty, integrity and reputation among the community itself.

Blogging:  New Relic has a blog (yes, I write there also) that is informative on many levels. Not just a blog that churns out marketing things about their own products, but instead a blog full of useful information about events, products, other company’s that partner with New Relic, community coding and hackathon events and all sorts of additional articles. The key here, is the New Relic Blog is actually useful to the developer community. Two great example here are the “Nerd Economy” which was just a fun entry, and the “Rails Rumble” involvement New Relic had.  This is what makes it an extremely valuable asset to the community, to New Relic itself, and to individual programmers & operations people as well!

New Relic's Blog - click to go there and have a read.
New Relic’s Blog – click to go there and have a read.

Basho

Full disclosure, I’m friends with a number of people here now thanks to RICON and because of their excellent interactions in the developer community, see here and here for more on RICON.

Blogging: Basho is another company that is doing this well. They’re focused primarily on partners, events related to OSS and Basho (such as Riak) and has a fair breadth of topics overall. This keeps people coming back, and makes the articles useful to the community. A great example is their activity around the Rails Rumble and the Basho Docs Update. Again, that recurring theme, the articles must be useful. No one should ever just stick marketing spiel into a blog entry and post it.

2. Do NOT waste our time (or yours), we’re overbooked already!

Try to connect events together with other companies and provide them as such. Give multiple reasons to come to conferences, meet ups or otherwise get out the door. If there isn’t reasonable reason to physically be somewhere, make it an online event, chat or some other type of communication. Better yet, in many cases, write up some documentation and let us developers RTFM! But whatever marketing departments  advocates and evangelists are doing, please coordinate a bit more so us developers (especially those that are writing a ton of app code) don’t spin our wheels getting value out of events.

From my personal perspective, I make it a point to help as many community members that organize meet ups and all to bring additional value – and if there isn’t enough value to merge with other groups. Bringing diverse backgrounds and polyglot ideals to a group isn’t a bad idea. Stay mono-lingual is a sure way when language priorities shift you won’t lose your community base. Now I’m going to harp on some groups that destroyed themselves, but eventually transformed by merging into other groups.

In Seattle & the Redmond area there used to be 3 (and I even have heard rumors of 4) .NET User Groups. With the advent of the extremely high value and dominance of the polyglot programmer (not that they were ever under-valued or anything). They all have since disappeared, but in very different ways. One lost because of a lack of content, then decreasing number of speakers, and eventually it died – completely. Another one actually ceased to exist because it merged into a group fo people that got involved in a number of other meetups that bridged development with a lot of other interests the attendees had. The last group actually polymorphed (eh, see what I did there with that programming term!) into a completely new group that is more open, more polyglot and fairly interesting. This is a perfect case of dropping a single tie to a single thing and branching out – or fading into nothing.

3. Don’t tell us not to communicate with our community!

Oh dear there is no better way to stifle innovation and favorable reputation of your software and products than to disallow your own company’s developers to publicly talk about it. It is absurd to kill this. The only company that I know, in the history of software, that has done this successfully is Amazon. But even Amazon only does it strategically. The companies that have done this completely are either dead or on their way to dying. To some degree Apple does this a little, but even in a tight lipped ship like Apple have developers talk about how or why they build things the way they do. They’re very proud of what they’ve built and they want to tell people.

The developers in a company are the absolutely best advocates for the products out of everybody. They may not be able to get out in the public, or even go out in public, but when they do and when they communicate if you’re running a good ship, that has proud developers, the community will know. Don’t forget either, there’s a few million us, that’s a force to be reckoned with in the market.

3.14159265359 Developers are indeed the king makers, don’t treat us like pawns!

RedMonk pointed out a while ago that “Meet the New King Makers: Same as the Old Kingmakers“. They’re on message, on target and very accurate as usual. If you want advice, information and a better understanding of the developer community, RedMonk is the analyst firm to check out for software development, you can forget the others.

I know there are dev shops out there that are amazing. There are dev shops out there that are atrocious. However those bad shops often suffer from heavy turnover, bad recruitment practices and even outright lying sometimes. It’s a bad situation, but just know if you hone your skills, communication skills and related abilities you as a developer won’t have to deal with those companies once you’ve cut your teeth in the industry.

To those dev shops that are meat grinders. You pay a heavy price, heavier than you might realize. Here’s why.

  • Turnover is ridiculously expensive. Many estimates range from 0.25x as much to 60x more expensive than maintain a solid team, good environment and positive conditions. Use google, read about it, turnover is a bad thing in many, many ways. (the rule of moderation does apply here)
  • A company with bad practices will NEVER, forget what you THINK you get, but the company will never achieve any type of competitive speed, quality or velocity of development compared to a dev shop that treats their developers well.
  • You will continuously create poorly designed interfaces, user experience and generally create a negative environment in which to operate, the company will never acheive its true potential. Developers are notorious for telling it like it is, if you make them unhappy, trust me when I say your entier company and the company’s reputation will be known very quickly among the developer community. Not only will you have to hire from outside of the area, you likely won’t be able to get A Game coders ever. They simply will not exist for a meat grinder shop.

There are ways for this to be remedied, but it is a very hard road to travel, far harder than any technical challenge to face. This challenge also takes, at minimum, years to truly fix once it has happened. So fix it, stop hiring warm bodies and work at being a good place for human beings to work.