Tag: writethedocs

Write The Docs Bring Forth New Understanding From Documentarians @WriteTheDocs

The Write The Docs Conference was started in 2013 as a simple idea. Bring together those that write professionally in technical fields, creating documentation, educational papers, scientific research or other ideas of this nature. Several people got together to organize this, thinking that even a moderate turn out of writers would be considered a success.

However a moderate turnout of 50 or 60 it wasn’t, it was a huge turnout of hundreds of people. Maybe I should say documentarians? Energy was high and individuals were ecstatic to meet others working on this oft overlooked area of technical work. It was such a great turnout and solid, useful and valuable energy among everyone that the organizers pushed forward and decided to have two conferences this year. One in Europe in the grand city of Budapest. The Write the Docs Conference will be back in its birth place of Portland, Oregon.

With the Budapest over I’m looking forward to getting a review of the event from Troy Howard @thoward37 and experiencing this years conference in person. If you’re looking to go, be sure to get tickets soon, they’ll very likely sell out of space.

Thoughts and Questions

This however brings me to the culminating point of this blog entry, that was ignited at the conference and inspired me to do more than just dwell alone in pondering what, when, how and where to write documentation. I started wondering and talking to people regularly about things related to documentation.

When should I start writing documentation?

Sometimes, it’s a good idea to start writing documentation before any coding actually starts. It’s a great idea to start documenting the ideas, thoughts around workflow and related matters pretty early. It helps to write down thoughts because it helps to confirm understanding and ensure more concise communication. At least, that’s what I have found. I wouldn’t be surprised if others experience this too if they give it a try in the earlier stages of a project.

How should I write documentation?

This is an interesting matter. Is it in story form? Such as in the form of a user story or that of a fictional story of someone using the application that would prospectively be built. Should just the entities, domains or other elements be written about? What should be written about these things at such an early stage? Isn’t this all part of BDUF (Big Design Up Front, and horrible anti-pattern)?

Watching out for BDUF is critical to success. Avoid it with energy and gusto. However confirming the entities and domains of a project, writing them down so others can more decisively understand what they are is important and useful. Writing stories of the application, also can be extraordinarily useful!

Many other questions come up and I’d love to see material on practices and ideas others have had. This is one of the big reasons while I’ll be attending Write the Docs. I hope to see you there, maybe we’ll get some answers and ideas wrapped up into some documentarian solutions!

For some great photos of the Budapest event…

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!

Write the Docs, Railsconf Portland, RICON East, Node PDX, Vancouver Polyglot, Open Source Bridge and OSCON…

…if you are deciding what to attend this year, here’s the top of the list.

Just a few key conferences that will kick ass in technical & academic content. The other great thing about these conferences is that they either have a “code of ethics” or are reknown for real conference diversity vs. the “hey a bunch of privileged sameness all ended up in this room purely out of meritocracy” nonsense. So you can rest assured that at these conferences you’ll have interesting conversations, be actively involved in things that will expand our personal sphere of the world and in the end leave you dramatically more enriched than those “corporate warm body vacation conferences“. This list doesn’t mean I’ll be able to make it to all of them, but each conference I’m in some way intimately involved with and fully support with the “Conference Seal of Approval“! So here we go…

Write the Docs – April 8th and 9th – @writethedocs – A new movement, to know where we are, where we’ve been and where we’re going. Get here, know how and why to bring knowledge forth through documentation. This is not your grandpa’s documentation.

Portland RailsConf 2013 – April 29th-May 2nd – @railsconf – The rails community has grown by leaps and bounds. Regardless of your love or hate for the framework, it’s revolutionized the way web applications are built over the last decade.

RICON East in New York City – May 13th & 14th – @basho – (I do work for Basho, but this is on here because RICON last year ROCKED and meets the requirements, come see for yourself!)  🙂

Node PDX – May 16th & 17th – @nodepdx – Troy Howard and I are putting this together, we’re working hard to make sure it’s more of what you want, more than it was last year and kicking to the curb the things you don’t want. So come hack some node, JavaScript and enjoy yourselves.

Polyglot 2013 – May 24th through the 26th – @polyglotConf – Open spaces, with tons of really, truly smart people with no presumptuous marketing and sales bullshit to get in the way. This is about software development, across the realms of frameworks, languages and more.

OS Bridge – June 18th through the 21st – @osbridge – open source bridges the divide here and new thinking is created. You have to attend to see…

OSCON – July 22nd through the 26th – @oscon – This is the premier open source conference in North America. It’s in Portland. Nuff’ said.

I’ll be at a few more conferences this year, but these are the key conferences, if you have to pick one to go to, it should be on this list. If you can go to one or two others, pick em’ from this list. Software + Data + Giant Phat Data + NoSQL + Future Thinking + Leaders o’ Thoughts == Top Conference List.

See ya there. Cheers!

The Friday Wrap Up: Write The Docs, Basho Coworking Office Hours & Node PDX

Wow, so this week has been an intense return to Portland for me. I got back earlier in the week and hit the ground doing a bit of catch up after being on the rails for two weeks to Denver, over to San Francisco and then back up here to Portland. The whole time cramming my brain full of Erlang, getting ramped up on efforts to help bring Riak to everybody that it can help, expand the open source community and do what I do. Expand the community and the risk taking, code inventing, hacker of hardware, and curious ideas that we all have as best I can.

Turning from looking back and looking forward, getting into a proactive view of events coming up there are a couple things I want to let everybody know about. They’re all intertwined here in the Portland Tech Community and well beyond, with events in Seattle and Vancouver BC coming up sooner than later!

Basho Coworking Office Hours

The Riak Products; Riak, RiakCS and Riak EnterpriseDS
The Riak Products; Riak, RiakCS and Riak EnterpriseDS

These events are every two weeks, starting this Monday. The meet is at NedSpace, we’ll grab the excellent Butcher’s Block Table and converse, code together, implement or deploy Riak and generally answer, present or find the information you need. Feel free to come in and join at anytime during 9am-11am on Monday the 4th, and every two weeks hereafter. You can RSVP here (meetup.com) or here *(eventbrite). For those that are RSVPed and show we’ll have various swag. Prospectively after building some momentum we’ll start bringing in some premium coffee or other beverages to help kick off your day.

Write The Docs

Write The Docs
Write The Docs

This is a new conference here in Portland that is being put together around documentation, document driven development and topics surrounding this oft overlooked and extremely important aspect of software development. As one would expect, it has a github repo.

Currently there are some speakers, but the call for proposals is still open, so check it out and if you’re interested in speaking jump in there and add to the conference and growing conversation! Here’s a short description from the conference site about what Write The Docs is about,

“Write the Docs is a two-day conference focused on documentation systems, tech writing theory, and information delivery. It will be held on April 8-9 in Portland, Oregon.

Writing and maintaining documentation involves the talents of a multidisciplinary community of technical writers, designers, typesetters, developers, support teams, marketers, and many others.

This conference creates a time and a place for this community of documentarians to share information, discuss ideas, and work together to improve the art and science of documentation.

We invite all those who write the docs to spread the word:

Docs or it didn’t happen!”

Speakers so far… there are more coming!

Nóirín Plunkett Plunkett AKA @noirinp the Curator of People 

From the recent speaker announcement, “Nóirín Plunkett is a jack of all trades, and a master of several. By day, she works for Eucalyptus Systems, as a geek<->English translator, and general force multiplier. She’s passionate about community, communication, and collaboration. Nóirín got her open source start at Apache, helping out with the httpd documentation project.”

Kenneth Reitz AKA @kennethreitz the Wandering street photographer and moral fallibilist & Pythoner

From the recent speaker announcement, “Kenneth Reitz is the product owner of Python at Heroku and a member of the Python Software Foundation. He embraces minimalism, elegant architecture, and simple interfaces. Kenneth is well known for his many open source projects, specifically Requests. His projects are always well documented, and he is the curator of the The Hitchhiker’s Guide to Python, which documents best practices for Python developers.”

Jim R. Wilson AKA @helixb the jimbojw and helixb and…

From the recent speaker announcement, “Jim R. Wilson started hacking at the age of 13 and never looked back. He has contributed to open source projects such as MediaWiki and HBase, and managed the large-scale documentation system at Vistaprint. He’s co-author of one NoSQL book, and currently writing a node.js book.”

The perpetrators of this conference are the reknown Troy Howard @thoward37, Eric Redmond @coderoshi and a fellow tech cohort I’ve recently met at The Side Door Eric Holscher @ericholscher.

Node PDX

There’s an announcement coming real soon about this!