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.

In-memory Orchestrate Local Development Database

I was talking with Tory Adams @BEZEI2K about working with Orchestrate‘s Services. We’re totally sold on what they offer and are looking forward to a lot of the technology that is in the works. The day to day building against Orchestrate is super easy, and setting up collections for dev or test or whatever are so easy nothing has stood in our way. Except one thing…

Every once in a while we have to work disconnected. For whatever the reason might be; Comcast cable goes out, we decide to jump on a train or one of us ends up on one of those Q400 puddle jumpers that doesn’t have wifi! But regardless of being disconnected from wifi, cable or internet connectivity we still want to be able to code and test!

In Memory Orchestrate Wrapper

Enter the idea of creating an in memory Orchestrate database wrapper. Using something like convict.js one could easily redirect all the connections as necessary when developing locally. That way development continues right along and when the application is pushed live, it’s redirected to the appropriate Orchestrate connections and keys!

This in memory “fake” or “mock” would need to have the key value, events, and graph store setup just like Orchestrate. With the possibility of having this in memory one could also easily write tests against a real fake and be able to test connected or disconnected without mocking. Not to say that’s a good or bad idea, but just one more tool in the tool chest doesn’t hurt!

If something like this doesn’t pop up in the next week or three, I might just have to kick off this project myself! If anybody is interested please reach out to me and let’s discuss! I’m open to writing it in JavaScript, C#, Java or whatever poison pill you’d prefer. (I’m not polyglot to limit my options!!)

Other Ideas, Development Shop Swap

Another idea that I’ve been pondering is setting up a development shop swap. I’ll leave the reader to determine what that means!  😉  Feel free to throw down ideas that this might bring up and I’ll incorporate that into the soon to be implementation. I’ll have more information about that idea right here once the project gets rolling. In the meantime, happy coding!

Configuring Node.js Web Applications… Manually || Convict.js

There’s more than a few ways to configure node.js applications. I’ll discuss a few of them in this blog entry, so without mincing work, to configuring apps!

Solution #1: Build Your Own Configuration

Often this is a super easy solution when an application just needs a single simple configuration. Here’s an example I found that’s pretty clean that Noli posted on Stackoverflow to the question “How to store Node.js deployment settings/configuration files?“.

[sourcecode language=”javascript”]
var config = {}

config.twitter = {};
config.redis = {};
config.web = {};

config.default_stuff = [‘red’,’green’,’blue’,’apple’,’yellow’,’orange’,’politics’];
config.twitter.user_name = process.env.TWITTER_USER || ‘username’;
config.twitter.password= process.env.TWITTER_PASSWORD || ‘password’;
config.redis.uri = process.env.DUOSTACK_DB_REDIS;
config.redis.host = ‘hostname’;
config.redis.port = 6379;
config.web.port = process.env.WEB_PORT || 9980;

module.exports = config;
[/sourcecode]

…then load that in with a require…

[sourcecode language=”javascript”]
var config = require(‘./config’)
[/sourcecode]

The disadvantage is when the application gets a little bigger the configuration can become unwieldy without very specific, strictly enforced guidelines.

Solution #2: Use a Library/Framework Like Convict.js

The use of a library provides some baseline in which to structure configuration. In the case of convict.js it uses a baseline schema that then can be used to extend or override based on configurations needed for alternate environments. A first steps in setting up convict.js for the fueler project looks like this.

Setup a convict.js file:

[sourcecode language=”javascript”]
var convict = require(‘convict’);

// Schema
var conf = convict({
env: {
doc: "The App Environment.",
format: ["production", "development", "test"],
default: "development",
env: "NODE_ENV"
},
port: {
doc: "The port to bind.",
format: "port",
default: 3000,
env: "PORT"
},
database: {
host: {
default: "someplace:cool",
env: "DB_HOST"
}
}
});

// perform validation
conf.validate();

module.exports = conf;
[/sourcecode]

The main two configuration values are the environment and port values. Others will be added as more of the application is put together, but immediately I just wanted something to put in the project to insure it works.

Next get the convict.js library in the project.

[sourcecode language=”bash”]
npm install convict –save
[/sourcecode]

The save gets it put into the package.json file as a dependency. Once this is installed I opened up the app.js file of the project and added a require at the top of the file after the path require and before the express() call.

[sourcecode language=”javascript”]
var path = require(‘path’);
var config = require(‘./config’);

var app = express();
[/sourcecode]

In the app.set line for the port I changed the setting of the port to be the configuration parameter.

[sourcecode language=”javascript”]
app.set(‘port’, process.env.PORT || config.get(‘port’));
[/sourcecode]

Now when I run the application, the port will be derived from the config.js file setting.

Now What Did I Do?

I’ll write more about this in the near future, but for now I’ve run into something not being setup right. I’m still working through various parts of customizing my setup. In the instructions for convict.js, which aren’t very thorough beyond the most basic use, is how to insure that the other environments are setup with *.json files. What I mean by this is…

I’ve setup a directory with three json files. It looks like this.

My Config Directory
My Config Directory

Each of these files (or at least one of the files) I would think, based on the instructions, get loaded and merged into configuration based on the code in my app.js as shown below.

[sourcecode language=”javascript”]
var env = conf.get(‘env’);
conf.loadFile(‘./config/’ + env + ‘.json’);
[/sourcecode]

The order of override for the configuration values starts with the base config.js, then any *.json files override those config.js settings and any environment variables override the *.json set configuration variables. Based on that, unless of course I’ve missed something for this snippet of code, I should be getting the configuration settings from the *.json files.

My config file data looks like this. Since it is using cjson I went ahead and stuck comments in there too.

[sourcecode language=”javascript”]
/**
* Created by adron on 3/14/14.
* Description: Adding test configuration for the project.
*/

{
"port": {
"doc": "The port to bind.",
"format": "port",
"default": 1337,
"env": "PORT"
}
}
[/sourcecode]

Until later, happy coding, I’m going to dive into this and figure out what my issue is. In my next blog entry I’ll be sure to post an update to what the problem is.

Oh, and that fueler project. Feel free to ping me and jump into it.

Andy Piper & Troy Howard, Now Twitter is up to Something!

Twitter is up to something. I’m betting it’s something good.

In the last 2 weeks I’ve found out two fellow coders are rolling into the Twitter family. These two people are top tier talent, so I’m just assuming Twitter had their act together when they went after these two new recruits. So who are these two individuals? Andy Piper and Troy Howard, two people everybody keeps track of. Wait, you do keep track of these guys right? Hmmm, if you don’t it might be high time you need to get in gear and follow them! Here are their deets, so you’re in the loop.

Andy Piper
Andy Piper

Andy Piper @andypiper, heading over to become Developer Advocate in London. Andy has been a great advocate over at Cloud Foundry. I only assume, as many who have used the Cloud Foundry Platform, he’ll continue to be an advocate for it. I’m super excited to see the efforts Andy leads forward with in this new role with Twitter. I’ll be keeping an eye out and hopefully this year landing in London to visit for a few lines of code and a brew or two.

Troy Howard
Troy Howard

Troy Howard @thoward37 is heading over to become the Technical Documentation Super Genius (my label) to which he humbly refers to as Documentarian. He’s helped lead projects like Node PDX Conf (which he and I stumbled ourselves into 2+ years ago) and he’s since knocked out work with organizing Write the Docs,

hujs
hujs

Hujs (check out Glenn Block’s write up) and others! Besides being a mad awesome conference organizer he’s all over the Portland tech community, code space & devops world.

For other trend setters and coders that get shit done and make waves, check out my Awesome Coders category. I’ve introduced more than a few top tier amazing people over the years that I’m totally stoked to have worked along side, hacked with, coded with or otherwise been involved with in the software & hardware industry!

Summary => References =>

So begs the question, “what’s Twitter up to eh?“