Zac's Blogon software…

When I was in high school reading Franz Kafka’s The Metamorphosis I learned one of the most invaluable lessons of my life; every piece of good writing simply must begin with a well formulated and famously interesting first sentence. There were other themes the teacher wanted to discuss such as transformation and existentialism, but to my young pragmatic (future programmer) mind none of them were as logical as the first sentence rule. I learned this lesson so well that some of my best writing over the next few years was never committed to a page.

Hugh MacLeod suggests in Ignore Everybody: and 39 Other Keys to Creativity that I have created a mental pillar to hide behind which provides  opportunity for me to disengage from a creative and possibly productive activity such as writing.  He is exactly right.

We create pillars in the software industry all the time because software systems are complex and not predictable and our craft is at its core still a largely creative endeavor.  Personal pillars like mine above save us from putting ourselves out there to expose our creative (or lack thereof) inclinations.  Organizational pillars such as a policy preventing the use of open source software exist; well I am not sure *why* they exist but they do.

The complexity inherent within any software project leads to one of the most common pillars which I will refer to as requirement explosion; otherwise recognized as the phenomenon that prevents you from finally starting that open source project that you have been thinking about for months because you first need to come up with a project name and a description with which to create your github.com account (or should it be google code or sourceforge?) but before that or at the same time you should have a project website ready that provides your vision for which you will need to acquire a domain name that ideally matches the github.com name (that you haven’t created yet) as well as the visual studio solution name which by the way you probably need to create ASAP so users have something to download once they stumble upon your project.  Requirement explosion is paralyzing as we fear starting the first task without fully understanding the necessity and order of all the tasks and thus we do not move forward.

The spirit of this example actually occurs in some form in almost every project and team I have worked on.  No matter the level of technical talent, no matter the brute force hours; pillars exist that prevent us from excelling at what we do best; using technology to create value for our users. 

Towards this end and in the interest of getting things done I intend to identify pillars created by me and around me and tear them down.

I stumbled upon Programming Bits and Atoms by Neil Gershenfeld which I found both eye opening and a little inspirational. The premise of the talk is that computer science is founded upon an abstraction of the physical world which is beginning to break down and that in the future computer science and physics will converge.

Particularly compelling was an example of the unacceptable cost not of creating smart building technology but of deploying (and supporting and troubleshooting) the network topology required for such technology using our current IP stack. Internet 0 is solution that changes the game.

I took this video as a subtle reminder that we as software developers must continue to hone our craft. Microsoft.NET, Java, Ruby; these are tools that we use to solve problems today but they will not be the tools we use tomorrow. Sometimes I catch myself thinking; how can I solve this problem with a Microsoft.NET application?. I should be thinking; how can I *best* solve this problem? Maybe that means spending a little less time becoming an expert in a particular tool and a little more time becoming an expert in delivering solutions that provide tangible value to customers.

The future looks incredibly promising for our industry; there is so much interesting work to be done that we can’t afford to stop learning for even one day.

The collection of stack* websites continues to grow.  The latest offering stackoverflow careers beta is a neat idea.  It will be interesting to see if it gains any traction. 

I signed up for an account and created a first cut CV which you can see here:

http://careers.stackoverflow.com/zacharyruiz

This site is definitely one to keep an eye on!

A colleague posed an interesting question today; if I was starting a new project for a client from scratch (ground zero, day 1) what documentation would I want to put together to capture the business requirements?

Of course the real world answer would vary from client to client.  More times than not the business requirements would mostly be defined and documented by someone else before I was brought onto the team.  Likewise teams often already have a preferred process in place with document templates, etc.

But just for fun; if I was tasked with starting the documentation stack for a brand new project today, this is what I would do…

1.) Brainstorm

My brainstorming tool of choice is FreeMind. 

I would sit down with the primary project stakeholder(s) and capture any and every idea we can conjure about the system we want to build.  No idea is too big or too far out for the mind map; this should be a fun exercise to generate some excitement and momentum for the project.

2.) Capture Requirements and Use Cases

The next step would be to sit down with *all* the project and product stakeholders and refine the wild ideas from the previous exercise into something real.  The important concept here is the brainstorming that happened above are the ideas of myself and one or two people while at this stage we want to capture the ideas of everybody else including the users.

The form will be a document that summarizes the business case (goals, scope, objectives) as well as requirement considerations and important use cases.  I say requirement considerations because these are not the final requirements, but rather a stepping stone on the path towards the final requirements.  If you believe that requirements are revealed as opposed to created then this document is your bridge to somewhere.

I use the following categories when interviewing the project stakeholders and users:

I am not sure where I came across this list and I almost never wind up with a ton of stuff in every single category but this list really gets me thinking about other important facets of the system on top of core functionality.

The use cases in this document will include the standard sections: goal, actors, pre-conditions, paths, etc.  When this document is complete everybody on the project should be able to read it and understand it and be on the same page and it will be important to keep this document up to date throughout the project. 

3.) Formulate User Stories

I prefer to work with user stories as opposed to formal requirements from this point out.  A large batch of the user stories can be gleaned from the document above and entered into something like TargetProcess.  The sooner I can get to this phase of the project the better; but not at the expense of the previous two steps.  The most important consideration moving forward is that I am not allowed to create user stories when I feel like it.  I must get some small version of the system in the hands of the stakeholders and users so they can refine and add to the backlog of stories while I continue fleshing out the documentation stack with design documentation, architecture diagrams, a test plan, etc.

As a software developer it is my responsibility to maintain connections between my work and the real world.  I cannot afford to code features that no one will use, to write documents that no one will read, to use tools that do not add value.  I love getting lost in the code for weeks as much as anyone, churning out feature after feature while experimenting with the latest productivity tools.  But ultimately if these efforts do not create value for my customers they are best suited for a hobby.

It is no longer good enough to exist as a software developer following a given software process.  I must constantly step away from my laptop to run my code on other people’s machines;  working code on my machine means absolutely nothing.  I must question *everything*;  my intuition regarding  look and feel of a graphical user interface is meaningless.  I must keep looking after the first solution to a problem presents itself; the second solution or the third may provide more value to my project.  I must never do anything for only one reason;  my time is too valuable to waste killing one bird with one stone.  I must assume nothing; talking to my users face to face on a regular basis is the only way to understand their ever changing realities.

If I sit at my laptop and code away day after day I may be having fun but I am not doing my job.

I read a good book this week that inspired me to get in the game.  I intend to use this blog to clear my head on the subjects of software and technology.  Along the way I will improve my writing, use the active voice and learn to communicate more effectively.  Target audience…. me.