Tuesday, July 8, 2014

New ThoughtWorks Technology Radar out today

Four trends are identified in the Thoughtworks strategic IT report called Technology Radar published twice a year. The most important one for me is the one concerning JavaScript technologies and the challenge it brings for understanding. That is the reason that I'm developing my new course, JavaScript Powered Web Apps focusing on the language's application to building client-side logic for web pages and developing more with the browser. And it's been challenging without the guidance of book authors and coordinating corporations.
Here's the full excerpt on JavaScript:
Churn in the JavaScript World — We thought the rate of change in the Ruby open source space was rapid until the full rush of JavaScript frameworks arrived. JavaScript used to be a condiment technology, always used to augment other technologies. It has kept that role but expanded into its own platform with a staggering rate of change. Trying to understand the breadth of this space is daunting, and innovation is rampant. Like the Java and Ruby open source spaces, we hope it will eventually calm to at least a deluge.
The other three trends were 
  • Microservices and the Rise of the API (also somewhat aligned with the JavaScript trends), 
  • Conway's Law ("organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations") and
  • Re-decentralization 

Monday, April 21, 2014

JavaScript Powered Web Apps - new programming course

The world of web programming is moving ahead into what should be called Web 3.0 (the semantic web is just a pipe dream). It's using JavaScript as a unifying layer and re-imagining how the web can do what it does without the benefit of large back end frameworks. Web 1 was delivering files to a client. Web 2.0 was letting clients think they were in control by faking a desktop application over HTTP. And now we can have a true application that has been enhanced with networking to services in 3.0.

For the next several months I will be developing a new course to complement the classes that I wrote a few years back on HTML5, CSS, jQuery, jQuery Mobile, and JavaScript that bring these components together. I see tooling on web applications starting to mature and it is the right time to start to promote a new style of web application development. Except that there's no one way to do anything yet. Adobe is getting close to providing another great IDE with Edge Code but I think we're a ways off yet. Even Google might become a player here with their IDE code named Spark built with Dart and Polymer.

The new course, JavaScript Powered Web Apps, will walk students through building a "site" using combinations of node.js, nginx, SASS, Mongo, Bootstrap, Github, jQuery, jQuery Mobile, Grunt, AngularJS, Knockout, Express, etc. I'll probably do four days of sample sites and then show a web work flow and let students choose their own tools.

The course will assume some programming or design experience with a web site but most of the exercises will be scripted so that anyone can follow them. The students that likely will be most interested are those that don't have the back end skill set and see a tremendous advantage in learning only one language to do both front and back end coding. That means that anyone from high school that has learned the basics of HTML and CSS can enroll.

A lot of the training is on the administration and workflow of the tools which is harder to learn from books. I'll try to capture what I can for the exercises but if anyone has suggestions, I'm willing to listen. And as always, the class will continually be updated as the tools rev and newer tools emerge.

For instance, I'm still waiting to see how Famo.us is going to impact the animation tools. It looks incredible but won't be completely public until May 19th when HTML5 Dev Conference in San Francisco starts. And I want to spin up a partial.js site as well I think. But I'll never know until it's finished. After all, a project's requirements are never finished until the project is over.

Thursday, January 23, 2014

Documentation as a control mechanism - not! Think communication.

People associate documentation in Agile with waste. In fact, the Agile Manifesto prefers "working software over comprehensive documentation" but does that mean that the purpose of documentation is secondary to the output of the project? Agile set us up with a poor dichotomy. I mean I prefer getting a paycheck over driving to work. Maybe we're asking the wrong question.

I don't see documentation as an optional part of the project. It's definitely an output and can be measured and that is the allure of the artifact. The traditional usage of documentation in a project is as a control mechanism when I look at the process outputs. It's often managers and specifically project managers who finalize a phase with the documentation. It's what they do. They design their work package by understanding the scope of the effort and if there is something measurable at the end it becomes a good work package.

Back in the darker ages of procedural coding, there was a movement to measure code by what it did. That entailed putting an estimate on the smallest granular operations of the computer in the code itself. That worked for awhile when the code was consistent in its granularity. But code has changed and what we can hide in a line of code has become enormous. The function point estimation methods died.

Now we estimate, if at all, with a measurement of work package time completion and complexity (from the programmer's perspective) or confidence (from the project manager's perspective). The dependency is on the work package design. If we don't have a good description of what it is we're going to do, we can't plan it. Many projects flounder from a lack of analytic description.

So where does this good description come from? Well, your requirements are the place to find these descriptions. Of course, the best requirements are ideally the needs and wants of the stakeholders massaged in to testable work packages detailed down to repeatable tasks so that no business questions have to be asked constrained by project limitations. But in reality, they are more of a garbage dump of what people said in excruciating long meetings.

The requirement document gets written and then we're on to the next phase. Follow along on your Gantt chart please. As a programmer, my input should be the output of the analyst. But with all the hubbub in programming circles about how to organize and manage testability, it looks like the analyst isn't doing a very good job. I don't see much evidence of usable requirements from my point of view either.

So, the Agile people are right. Processes without consumers are pure waste. Let's right-size this documentation by eliminating it. No one used it anyway. But what are we losing? We're losing the ability to record a decision and the to think about the design of the business. Of course, if it wasn't good for the programmer, then it was useless.

But let's consider that the analyst can benefit the programmer. Then the documentation becomes a stepping stone to better code. Then there is communication of the needs of the business. Then there is less thinking on the role of the programmer who gets to focus on writing well-structured and reusable code.

The role of the documentation is really that of communication when the project scales. If you are the sole stakeholder and programmer, you probably have all the requirements circling in your head at any one time. No documentation is necessary. If two people know exactly what has to be done after a good agreeable meeting, no documentation has to be created. But if there is a memory loss, a sick day, a new member to the team, you will need some documentation. The need for documentation increases as the need to communicate increases.

The management of documentation needs a metric instead of lazily setting the goal to that of creating a greater return on investment (ROI). Just how do you measure that? My standards for measuring are in the more subjective realm whereby you produce the documentation, ask the user of that documentation if they understand, and then see if they are able to do their tasks without any further questions. The quality score descends as the need for answers or the amount of perceivable confusion increases. Get feedback.

Documentation is not a gate to the next phase and to be signed off. I'll take the stance a little further than the traditional "living document" style of writing. Since it is to be a communication mechanism, it has to always communicate the current understanding of what the project is about. Anyone and everyone can be a contributor but the use cases / user stories / work packages should be maintained by the analyst / technical writer role so that they achieve the best level of testability and detail. Wikis are good.

The trend of "barely good enough" documentation, I think, is allowing the programmer to use their analytic skills in place of poor business analysis skills in the workplace, which is sad but the best workable solution to getting the job done. Stop producing unusable business documents and let the programmer get on with the code. Why are programmers strongly in favor of commenting their code and following Test Driven Development? Because those are the tools that get the documentation done a better way.

So, lets eschew the notion of controlling the project by requiring the project members to produce a result that isn't used in the next phase. Control the project by understanding the work package completions. The artifact that completes the work package is the code or the pseudo-code (the use case) in some form or another, not a project document.

So, is documentation is secondary to the output of the project? Getting a paycheck over driving to work is comparing the result with a task for getting that result. It depends whether you have to go to the office or not. Documentation is not secondary. It's just a question of whether you need to communicate more or not.