Month: April 2014

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…

Pluralsight Authors Summit – Meeting & Learning Really Talented People!

Finally, I’ve been able to wrap up my first blog entry on the Pluralsight Authors Summit 2014 (AS14)…

Classified

It all started with this. I’d received a mission.

NOTE: Click on any image to see the full gallery of images I took at the conference. My apologies for the dirty iPhone 5 camera lens.

I’ve been creating Pluralsight courses for a while now, with two to my name; Riak Fundamentals and Docker Fundamentals. I’ve got others in the works, and a lot of great suggestions that I’ll be blogging about in the very near future. However this weekend I headed to Salt Lake City for the Pluralsight Authors Summit.

I arrived at the airport, a 3 minute walk out and onto the light rail to downtown. I ranted via Twitter on my layover at the mess that SEATAC (Seattle & Tacoma’s Airport) is. Salt Lake City makes SEATAC look like an engineering catastrophe. So it was really nice to land in SLC and be able to walk right onto the train into town.

…that led into my admitted love for Seattle, I can’t harsh too bad on the emerald beauty…

Immediately upon leaving the airport it did seem a bit like I’d entered Mordor. Looking into the far distance the sky almost burned a brownish red and seemed to have endless darkness as far as I could see. With a twisting cloud or fog structure pushing down upon the southern view from the airport.

Ok, ok. It actually looked like this. But really, check that out, it’s kind of wild looking!

Along the way it cleared up and there were some amazing views to see of the mountains in the distance. It doesn’t really matter which way you look, you’ll see amazing vistas all around.

I rolled on into town and got to see a bit of downtown as the light rail rolled through town. It seems that Salt Lake City has a lot of bike lanes and related things, albeit I didn’t see any bicyclists anywhere. Overall what I could accrue was the city was extremely clean, well kept and the people – which I got to experience the rush hour while coming into town – were calm and chill as I often expect west coast cities to be.

I then got off at Little America Hotel where the conference was taking place. I couldn’t have asked for an easier ride, with the front door of the hotel being barely across the street from the light rail stop. I figured out my room, headed to check in and got some cool swag, then off to drop all my pack off at the room.

Once I rolled back into the main summit conference center I introduced myself to several people and got my photo taken. Somewhere, at some point, you’ll be exposed to my crazy mug somewhere again. I’ve warned you.

I talked camera and video gear with Phil Hunter. Phil has just started working at Pluralsight and is getting some great work put together for them.

After a bit of talking and introductions to new people, we all rounded up and sat down for dinner that evening. It wasn’t just dinner though, there was gambling setup with prizes and more. That unto itself was pretty cool, but being the non-gambling person that I am, I went straight to the food. Which I gotta say was really good! I even got to experience two glassholes (Jim Wilson @hedgehogjim | Jim’s Author Page and Llewellyn Falco @LlewellynFalco | Llewellyn’s Author Page who are excellent crew) try to setup some magic pixie dust unicorn trick with their Google Glasses.

Jon, Shannon, Julie and all of us we sat helplessly while they configured the glasses to do… well I don’t think we ever figured it out really. But a great table to sit at. We had a good dinner. I wrapped up and others went to gamble while I went to get some recovery sleep.

Saturday

Saturday kicked off a set of talks:

  • Key Note: Aaron Skonnard @skonnard CEO of Pluralsight – great to get the big picture and see where the company is headed.
  • Curriculum Overview & Future Direction – Fritz Onion @fritzonion & team dove into specifics of how we’ll grow offerings to bring more courses and material to subscribers in the coming year, making it easier to find, search for and use.
  • Continuous Improvement & Creating Compelling Technical Content with Geoffrey Grosenbach @topfunky.

Another great lunch was served, conversations were had and I got to introduce myself to even more great authors. After lunch I met Koffi Sessi @aksessi in person finally and we discussed courses, ways to improve and put together even better content and a host of other topics. We wrapped up with a promise he’d send me some of the music he listens to. Being we both of some really esoteric genres I’m looking forward to what he sends me.

After that I got to check out Video Workflow with Shawn Wildermuth @ShawnWildermuth and Authoring and Time Management with the Dane Down Under Lars Klint @larsklint. After dinner the evening wrapped up with X Things You Didn’t Know You Could Do With Your Blog by Chris Reynolds @jazzs3quence and Tips on Using Windows Azure to Host VMs for Recording Pluralsight Demos by Orin Thomas @orinthomas | Orin’s Author Page.