No Fluff Just Stuff

Devs in the ‘Ditch Slides Posted

Johanna Rothman — Tue, 21 May 2013 00:29:00 CDT

I gave a talk at Devs in the ‘Ditch last week when I was in London. I posted the slides on slideshare: Overcoming Three Pitfalls of Transitioning to Agile.

The very nice people at 7digital made a video and posted it, too. If you can take the time, watch the entire video. Rob Bowyer gave a great talk about kanban and theory of constraints. My part about overcoming these three pitfalls starts at about 42 minutes in.

There are many other pitfalls to transition. This talk had just three of them: the stories are too big, you need experts to do the work, and you implement as layers instead of through the architecture.

I hope you enjoy the presentation and the video.

Auto-Refresh for Play Framework Apps

James Ward — Wed, 15 May 2013 17:02:00 CDT

Over this past weekend I built a little tool for Play Framework app developers which auto-refreshes an app in Chrome when the source code or static assets change.

Check out a video demonstration:

For information on how to set it up, check out the project on GitHub:
https://github.com/jamesward/play-auto-refresh

Special thanks to Josh Suereth for helping me figure out the SBT magic.

Android Panel and Kiosk Apps

James Harmon — Tue, 14 May 2013 07:59:00 CDT

One advantage of doing business in the Chicago area is getting to see lots of manufacturers. The Midwest still builds stuff.

As an Android developer who gets to talk with many of the local companies I've recently noticed a pattern in the Android space that I wanted to share.

High end tools and machines often contain some kind of display that describes the status of the tool or provides a way to configure or operate the tool. And by "tools and machines" I'm covering a huge variety of products.

Look at the control panel for the new LifeFitness exercise machines below.

It is pretty clear that this could be done using an Android device (and I believe it is).

I call this kind of application a "Panel" app.

What 6 qualities differentiate this from a typical app.

Fixed in place (built into the machine or tool)

Custom user interface (doesn't follow the Android UI guidelines)

Other apps are unavailable or hidden (the user can't run their own apps)

Targeted to a very small set of devices (only runs on the tablet built into the machine)

Users engage with it frequently and over a long period of time (so they can learn custom interface)

interface with underlying machine or tool

The other similar, but slightly different, kind of device runs a single purpose app also. I call it a "Koisk" app.

The 4 characteristics of a Kiosk app

Public (think shopping mall)

Wider audience (user has brief use of it, so must be easy to use which means that it should work like apps the user is familiar with) follow design guidelines

Fixed in place (mounted on a wall)

Locked down (can only run target app)

These apps never appear in the marketplace but are great opportunities for Android developers. Keep them in mind when you search for your next consulting gig.

Book Review Functional Programming For Java Developers

Demian Neidetcher — Tue, 14 May 2013 00:00:00 CDT

First off, this is a small book. 72 pages including a glossary. I was able to read it on a plne ride from Louisiana to Denver. Like the tagline says, I hope I never need this book.

As the title suggests, the book is about making Java more functional. On my team we spend half our time in Groovy and half on Scala. I suppose we have done similar things in Groovy. The support that Groovy has for closures makes it easier than it would have been in Java.

He also covers what is coming in Java for more FP features like closures. The syntax looks clunky but I could see living with it if I had no choice.

I found the book useful in reviewing and appreciating where I’m at. How things were in Java and how nice things are in Scala. Even if you don’t need to do functional programming in Java right now I think this book is a good read. If my current gig fell apart and I had to do Java fulltime then I would grab this book to keep my sanity.

Securing Single Page Apps and REST Services

James Ward — Mon, 13 May 2013 10:06:00 CDT

The move towards Single Page Apps and RESTful services open the doors to a much better way of securing web applications. Traditional web applications use browser cookies to identify a user when a request is made to the server. This approach is fundamentally flawed and causes many applications to be vulnerable to Cross-Site Request Forgery (CSRF) attacks. When used correctly, RESTful services can avoid this vulnerability altogether. Before we go into the solution, lets recap the problem.

HTTP is a stateless protocol. Make a request and get a response. Make another request and get another response. There is no correlation (i.e. “state”) between these requests. This poses a problem when you need to identify a user to the system because one request logs the user in and another request needs to tell the server who is making the request.

Web browsers have an automatic way to store some information (i.e. “state”) on the user’s machine and then add that information to every request. This is called “cookies” and they provide a convenient way to create a correlation across HTTP requests. Most web frameworks have a built-in concept called “session state” which uses a unique token for each user. That token is stored in a cookie and automatically sent to the server on each request. Now the server knows how to identify a user across requests.

This approach is simple and works great until you realize the dark truth of CSRF. Usually a user is doing something that tells the browser to make a request to server and because the cookies are sent, everything is good. But suppose the user gets an email that says “Check out these funny kittens!” with a link to a malicious website. No one can avoid seeing funny kittens, so the user clicks the link. It turns out that the funny kittens website is a malicious website which now makes some requests to an application that only uses cookies for authentication. Perhaps the malicious request is to transfer money out of your bank account. Or perhaps it posts something on a social network. These requests will be identified AS THE USER because no matter what causes the request, the browser will send the cookies. This is CSRF and many web apps are vulnerable to it.

The root of the problem is using cookies as the sole method of identifying a user since no matter how the request is initiated, the cookies which include the authentication token are always sent to the server. One way to protect against this type of attack is to force each request to contain another token which is not automatically sent. Most web frameworks provide a way to do this but they are error prone because it often requires developers to explicitly enable it and the approach doesn’t always work well with Single Page Apps.

The Way Forward

The easiest way to do authentication without risking CSRF vulnerabilities is to simply avoid using cookies to identify the user. However each request must still send a token to the server to identify the user. This requires a token to be somehow “remembered” so that each request can manually send it. Luckily Single Page Apps provide a way to keep a token in memory across requests because the page never reloads.

But what if the page does reload and the authentication token is lost because that in-memory state has been cleared? Does the user have to log back in to get a new authentication token? That would not be a very good user experience. Browsers have a few ways to store data locally across requests. The easiest is to simply use cookies. Wait… aren’t cookies the root of the problem? Cookies themselves are not the cause of CSRF vulnerabilities. It’s using the cookies on the server to validate a user that is the cause of CSRF. Just putting an authentication token into a cookie doesn’t mean it must be used as the mechanism to identify the user.

When a Single Page App loads it can read the cookies (via JavaScript), grab the authentication token, and then manually send that token on each request through a custom HTTP header. This is safe because that malicious funny kitten site does not have access to the cookies. If it did, every website would have a severe security issue.

The flow with this approach may go something like this:

The user navigates in their browser to the application
The server returns a basic web page and a JavaScript application
The JavaScript application can’t find an authentication token in the web site’s cookies
The JavaScript application displays a login form
The user enters correct login credentials and then submits the form
The server validates the login information and creates an authentication token for the user
The server sets the authentication token in a cookie and returns it to the JavaScript application
The JavaScript application makes a request for some protected data, sending the authentication token in a custom header
The server validates the token and then returns the data

At step 3 if the JavaScript application does find an authentication token in a cookie then it can skip ahead to step 8.

At step 9 the server may not be able to validate the token in which case it should return a 401 (Unauthorized) response which the JavaScript application can handle by going to step 4.

There are a variety of ways to implement this approach but the real key is that the server doesn’t validate a user based on a cookie, it instead validates the user with a customer HTTP header.

This approach can be used over HTTP or HTTPS. But it is highly recommended that authentication tokens are only passed over encrypted connections which means you should probably only be using this approach over HTTPS connections. Whenever an application is not being used for local development it should automatically redirect HTTP connections to the corresponding HTTPS connection. In this setup make sure that the cookie containing the authentication token can’t be inadvertently transmitted over the HTTP connection by forcing the cookie to only be sent over HTTPS (an option which is typically available in cookie APIs).

Sample App

To better explain this approach lets walk through an example application. You can get the full source for the application from: http://github.com/jamesward/play-rest-security

This application is built using Play Framework, Java, jQuery, and CoffeeScript.

To run the application locally, download Play 2.1.1, extract the zip and optionally add the extracted directory to your system’s path. Then using a command line, navigate into the play-rest-security directory and run the following (assuming the play command is in your path):

play run

This will start the application which you can connect to in your browser at: http://localhost:9000/

You should see a login form which you can test out and once logged in, you will see the protected data and can add new data.

There are also a number of functional and unit tests for the application which validate the security of the application. You can run the tests locally by running:

play test

RESTful JSON Back-End Services

Starting with User.java you will see this is a typical database-backed entity using JPA. The User class has a property authToken which will store a single authentication token. In a real-world application you will probably want to allow a user to be logged in from multiple clients (e.g. different browsers). To enable this you could simply turn this into a list. You may also want to have some tracking on when authentication tokens are used, what IP address used them, and when they were created. The tokens could also be encrypted in the database.

The Todo.java file contains the Todo entity which stores a user’s Todos. Access to the Todo objects happen via the TodoController.java class. In this case the TodoController only has two methods, getAllTodos() and createTodo(). These methods are exposed via HTTP through the routes file. The TodoController has the @With(SecurityController.class) annotation which setups up a request interceptor so that every request made to the controller must go through the call method in the SecurityController.java class.

The call method in the SecurityController tries to find an authentication token in a custom HTTP header. If it finds a token then it tries to find a user with that token. If found the user is added to the HTTP Context (a place to store data for the duration of the request) and then the original controller method is called. Otherwise a 401 response is returned.

Both getAllTodos() and createTodo() in the TodoController use the authenticated user that was stored in the HTTP Context to either fetch the user’s todos or create a new todo.

The SecurityController class also has login and logout request handlers which are mapped to URLs in the routes file. The login method tries to locate a user by the provided username and password. If it succeeds then it creates a new authentication token for the user, then creates a cookie containing the token, and returns the token in a JSON response. The logout method uses the SecurityController interceptor to validate the user and then deletes the cookie that stores the authentication token and set’s the user’s authToken to null.

That is the RESTful back-end of the example app. Now lets explore the front-end.

CoffeeScript + jQuery Front-End UI

In the routes file you will see that requests to / are handled by returning public/index.html. This file doesn’t do much other than load jQuery and also load the index.min.js file which is compiled and minified by Play’s asset compiler. The source for that file is index.coffee and it provides the whole UI for the application. This example uses CoffeeScript because it provides a more concise and readable syntax for writing JavaScript applications.

When the page is ready the init function is called and the application attempts to find the authentication token in a cookie. If it can’t be found then a login form is displayed. If the cookie can be found then the displayTodos function is called. This function tries to fetch the user’s list of Todo objects and then display them. The request to fetch the Todo objects is a normal Ajax JSON request except that the user’s authentication token is sent in a custom HTTP header. If the server responds with a 401 error then the application calls displayLoginForm otherwise the user’s Todo objects are displayed. The createTodo function also sends the authentication token in custom HTTP header and the JSON data for the Todo within an Ajax request.

That is really all there is to the front-end UI. Most of the code in the CoffeeScript is displaying data and forms in the HTML through jQuery DOM manipulation. This DOM manipulation could also be done through one of the many client-side templating libraries.

Further Learning

The important point to remember is that using cookies for authentication opens up the possibility of CSRF attacks. Custom HTTP headers provide a more secure method of identifying users than cookies alone do. The combination of Single Page Apps and REST services provide the perfect opportunity to move away from cookie based authentication. This simple application illustrates how to implement this approach.

Learn more:

Individuals and Interactions With Gil Broza

Johanna Rothman — Mon, 13 May 2013 08:07:00 CDT

My friend and colleague, Gil Broza, is interviewing me for his Individuals and Interactions virtual training event. My topic? “Focus Keeps You Going.”

If you read my personal kanban series a couple of weeks ago, you saw how my focus kept me going. Even with a big interruption last week, due to a death in the family, I was able to maintain my focus, because I knew exactly what I had to do, to finish my work, to get ready for my trip today.

Gil has other great people in his event: Doc List, Ellen Gottesdiener, Mary Gorman, David Spann, Christopher Avery and Bob Schatz might be names you recognize. How about Rick Ross? David Spann? Caren DesBrisay? You might not recognize these names, and you should listen to what they have to say, too.

Check out Gil’s Individuals and Interactions training. Sign up. It’s a steal.

Succeeding with DDD - Documentation

Paul Rayner — Tue, 07 May 2013 12:40:00 CDT

I’m often asked about what teams doing Domain-Driven Design (DDD) should do in the way of documentation.The question What types of Written Design Documents are used in DDD projects?) came up on Stack Overflow and I started to write a response, but realized it was getting way too long to post there. So here it is.

When it comes to documentation, we need to begin with the end in mind. We need to understand why we are writing it in the first place: What purpose is each document intending to serve? The problem with a lot of documentation is that it is seen as an end in itself, rather than a means to an end, which is to deliver a quality product that meets an important customer need. This is why agile teams adopt the value of “working software over comprehensive documentation.”

However, documentation serves a number of important, and different, purposes. For each documentation artifact, ask: “Is this artifact to support the team now as it develops the software, or is it to support future development?” Depending on the answer to this question, approach the documentation in a different way. Let’s start with supporting future development.

The Problem of Tribal Mythology

Jason Smith in Elemental Design Patterns says the following about kinds of documentation supporting future development:

We know we should document our software; we know we should keep it up to date; we know we should commit to pen or screen the whys, the hows, and the reasons; but we also know it is a pain. It really is, so we don’t do it. What we have instead is a body of knowledge that is locked within the heads of developers, that is passed along in fits and spurts, when prompted and only where necessary, frequently without any comprehensive framework of common understanding among stakeholders.

As Jason points out, Grady Booch has popularized the phrase “tribal knowledge” for this kind of information artifact. Documenting for the future preserves the oral tradition by encoding knowledge that already exists. It supports the later transmission, socializing and sustainability of the “tribal knowledge” of the team.

So one type of documentation we create supports future development by preserving the oral tradition that teams develop along with the software. Without this kind of documentation “…the collected tribal knowledge degrades into “tribal mythology” (Booch). When this happens, no one really knows how the system ended up the way it has, and the knowledge is lost.

This kind of supporting, future-facing documentation is particularly relevant where such knowledge is not immediately apparent by reading the code, supporting tests and other artifacts. Such documentation is typically written after features/modules are implemented/delivered. It can be produced as the software is being built, but then there is the additional maintenance cost of keeping it up-to-date as things change.

Preserving Tribal Wisdom

So we want to avoid tribal mythology by documenting our systems as necessary. We want to capture and preserve for people to come the “tribal wisdom” that has been gained in the rough-and-tumble of developing the system. As Jason points out:

Tribal wisdom, however, is the virtuous flip side of this tribal mythology. It is prescribed action with understanding, how accompanied by why, and is adaptable to new environments, new situations, and new problems. It transcends rote copying, and provides illumination through a comprehensive discussion of the reasons behind the action.

At some point in the past, for almost every action or decision in a system, someone knew why it was done that way. Carrying those decisions forward, even the small ones, can be critical. Small decisions accrete into large systems, and small designs build into large designs. By ensuring that we have a strong tradition of knowledge retention that facilitates understanding, we build a tradition of tribal wisdom.

Favor Documenting over Documentation

So we support future development by preserving tribal wisdom through documentation, but what about supporting the team as they develop the product?

In the same sense that agile teams favor planning over following a plan, they tend to favor documenting (as an ongoing, just-in-time, activity) over creating a (once-and-for all) document. And in the same manner that their planning is focused around high-fidelity communication, customer collaboration and team interaction, any documenting they do tends to have the same goals and characteristics.

A plan is only useful until it needs to change, which is why agile teams focus on enabling and responding to change. The intention is the same with any documentation they create in service to building a software solution - it should not be painful, but rather serve the team in better understanding the problem space, and helping the team grasp what the solution needs to look like. Let’s look at some important characteristics of this style of documentation:

Characteristics of Useful Documentation

Trustworthy

This should have to go without saying but, like comments in code, much of the documentation that exists cannot be trusted. If you have documents that are supporting your development, make them living documents by keeping them up to date. They must be correct. They must speak the truth about the software and the business domain.

Malleable

Part of keeping documents trustworthy is enabling change. Documentation must be malleable - make it as easy to change as possible. Reduce the friction of having to change it. Documentation that is burdensome to change is less likely to be kept up-to-date.

Makeing it malleable typically means making it as lightweight and informal as possible. Prefer hand-drawn diagrams over created in a tool (such as Visio), prefer electronic over hard-copy. Only include the pertinent details. Indicate which things are tentitive, and which may be harder to change.

The important thing is to understand the purpose of each document, and ensure that it is kept up to date. As much as possible, push the knowledge into the code and the tests.

Accessible

Documentation must be as accessible as necessary. Things that the team is working on right now, I would expect to be on the walls of the team area. Just the same as many teams use information radiators such as burndown charts and task boards to track their delivery progress, I like to see sketches of design diagrams on the walls too.

I like to see a context map on the wall, showing the terrain the team is dealing with. I’ve worked with many teams that were not co-located, so we would put the the documents in shared folders, and on the wiki. Sometimes we would sketch on a whiteboard, and then take a photo of the diagram and put it on the team wiki.

Don’t let your wiki fall prey to the Tragedy of the Commons. Appoint a curator for your documents if necessary. But strive for team-ownership of the documentation, just as you strive for team ownership of the code.

Documentation and Doing DDD

DDD teams often find they have a leg-up with documentation, because they devote so much effort to distilling domain knowledge into the software itself via the domain model. Teams doing DDD are focused capturing the essence of the critical concepts of the core domain in the domain model itself. With DDD the rules, reasoning, assumptions and key business concepts are embedded in the software.

When I start with a team, the first thing we draw together is a context map. This diagram helps set them up for success in terms of knowing what context they are working in, how it relates to their core domain and the other contexts they need to interact with.

For DDD teams, and for software teams in general, the important thing should be not that the domain is documented, it is that it is understood, and that this understanding is shared among everyone connected with developing the software. Good documentation engenders a shared understanding of the business domain. Good documentation for a DDD team captures the essence of the reasoning around the domain model: a rich, expressive software model that enables significant business capabilities in the core domain, supporting the strategic goals of the business. Teams doing DDD accomplish this by simplifying domain complexity enough to provide a shared language and understanding, and embedding it in the code.

DDD is not prescriptive about documentation. What documents are produced usually has more to do with the team’s existing process than doing DDD. However, there are certain kinds of documentation that teams doing DDD do find very helpful. Let’s look at some of these.

Requirements Specification?

Many teams opt for user stories as items in a feature queue, prioritized by value to the business (i.e. “Product Backlog”, in Scrum terms). See my earlier blog post on user stories and DDD.

A team doing DDD could use a requirements specification document. But the trap with heavyweight, detailed specification documents is that they tend to separate design from implementation. As Mary Poppendieck writes:

The theme running through all of my experience is that the long list of things we have come to call requirements – and the large backlog of things we have come to call stories – are actually the design of the system. Even a list of features and functions is design. And in my experience, design is the responsibility of the technical team developing the system.

and…

I suggest we might get better results if we skip writing lists of requirements and building backlogs of stories. Instead, expect the experienced designers, architects, and engineers on the development team to design the system against a set of high-level goals and constraints – with input from and review by business analysts and product managers, as well as users, maintainers, and other stakeholders.

Agile teams tend to eschew producing detailed requirements specifications, preferring a more light-weight approach to describing what the system needs to do. The problem with such documents is that design decisions are made too early, with insufficient domain and technical knowledge, and having it written up in a specification tends to set that ignorance in concrete.

All too often, detailed requirements lists and backlogs of stories are actually bad system design done by amateurs.

The risk in this approach is that:

Separating design from implementation amounts to outsourcing the responsibility for the suitability of the resulting system to people outside the development team. The team members are then in a position of simply doing what they are told to do, rather than being full partners collaborating to create great solutions to problems that they care about.

Most teams I coach are following some form of agile process (Scrum, XP etc) and thus tend to focus more on rapid feedback loops and incremental development over producing copious amounts of documentation first. This tends to aid with modeling, as the documentation is produced as-needed, rather than to get through some “gate” in a prescribed SDLC process. The code itself is the design, paraphrasing Jack Reeves.

Some teams find it helpful to develop a list of use cases, a list of tasks the program is able to perform or some combination of both. I would experiment with what you find most useful for your team. Use cases have fallen out of vogue recently, but I am still a big fan of them.

Note that I am not against specifying requirements in written form, but rather entombing those requirements (i.e. what features the system should provide to meet the customer’s needs) in a large tome that locks-in the details of how the system should behave. I have utilized use cases in a lightweight, just-in-time way and found them very useful. See Alistair Cockburn’s article on Why I still use use cases for similar reasons to mine.

I would also strongly recommend using mockups and prototypes as much as possible.

Core Elements

I typically create a short document that captures the core domain vision statement and the context map.

Architecture

Architecture is largely orthogonal, but supportive, for DDD. I find the “4+1 architecture” approach to be the most useful. It is useful to keep in mind that, as Grady Booch declared in 2009, architecture is a shared hallucination:

Architecture is just a collective hunch, a shared hallucination, an assertion by a set of stakeholders on the nature of their observable world, be it a world that is or a world as they wish it to be. Architecture therefore serves as a means of anchoring an extended set of stakeholders to a common vision of that world, a vision around which they may rally, to which they are led, and for which they work collectively to make manifest.

Notice that in Krutchen’s approach, scenarios are the unifying thing. Reference scenarios are a more specific form of this. See my presentation on domain scenarios at the DDD Exchange 2012 for a walkthrough of using reference scenarios. In DDD reference scenarios describe the key business problems that the model needs to solve.

Reference scenarios will be the core domain business capabilities that the software, and in particular, the domain model, will enable. They often take the form of a short narrative, with a supporting diagram. Not starting out that way, but the key is capture the significant details that make the problem worth solving for the business.

George Fairbanks book, Just-Enough Software Architecture is the best book I’ve found on characterizing, describing and documenting software archtictures. I love the pragmatic, risk-driven approach to architecture that this book takes (the sections on modeling alone are excellent, though it defines DDD too narrowly for my taste). If you are looking for something more comprehensive in the software engineering tradition, then it’s hard to beat the definitive tome: Documenting Software Architectures.

Ubiquitous language

It can be helpful having a document that explains the Ubiquitous Language. Many teams develop a dictionary of significant business terms early on, and for a team with a business analyst this can be a very significant contribution. However, the same caveats mentioned above relating to separating design from implementation are particularly relevant:

In most software development processes I have encountered, a business analyst or product owner has been assigned the job of writing the requirements or stories or use cases which constitute the design of the system. Quite frankly, people in these roles often lack the training and experience to do good system design, to propose alternative designs and weigh their trade-offs, to examine implementation details and modify the design as the system is being developed.

So as with all the documents described here, the dictionary must be kept up to date to be useful. Such a dictionary can be an important start, but it shouldn’t be the end. I like to see it developed into a document that has diagrams showing important states of the model, and how the terminology of the domain model is used.

As terms change over time, such a document can be a good place to explain why these changes in language were made, since that kind of historical information won’t be obvious by looking at the code etc.

Informal UML diagrams

I am always sketching UML diagrams on whiteboards. It saddens me that many teams don’t see the value in this. I particularly find instance diagrams particularly useful in walking through scenarios with domain experts. I find that when the domain experts see the concrete, pertinent business data values in the “little boxes” in the diagram, it really helps with understanding what the model is expressing.

Many times when I work with a team that has an existing model, one of the first things I will have the developers do is walk me and the domain expert through a reference scenario on the whiteboard, explaining how the model supports solving the important business problem. This activity alone is often enough to show strengths and weaknesses of the domain model. Instance diagrams also really help with understanding aggregate boundaries, since aggregates are runtime artifacts.

Sequence diagrams can be very helpful for understanding the application flow from the UI, API, or context boundary down to the domain model. And also in understanding interactions between sagas, objects, domain services or aggregates (such as via application services or other infrastucture responsible for eventual consistency between aggregates).

To create electronic versions such I often use light-weight UML sketch tools such as Web Sequence Diagrams and yUML. I like the way these tools produce diagrams that look hand-drawn, which lends them towards being viewed as transient and gives the team permission to change them. One of the problems with producing high-quality UML diagrams is that it tends to communicate that they are “done,” and shouldn’t be changed. That they are finished.

Anything else?

I’m a big fan BDD tool such as Cucumber to create living documentation for the system, if the team has the skills and experience with such a tool. For example, the following feature file helps support the ubiquitous language supporting the underlying conceptual model represented in the domain model.

I’m biased towards Cucumber as a tool because I like the separation of steps in feature files and stepdefinitions encourages the separation of ubiquitous language from the technical implementation. The business terminology goes in the feature files, and should be refactored as the ubiquitous language is refined over time.

I am co-authoring the book BDD with Cucumber for Pearson/Addison Wesley. The book will cover doing BDD using Cucumber (Ruby), Cucumber-JVM and SpecFlow.

But it’s not the tool that’s most important, the same thing could be done with other acceptance testing frameworks such as Concordian, Fitnesse or Robot Framework. There’s an interesting discussion going on right now on the Agile Alliance Functional Testing Tools (AA-FTT) mailing list about these frameworks and the various tradeoffs they provide. The important thing is the improvements I see in communication and collaboration when teams use these tools to refine acceptance criteria for user stories.

Standalone vs. Combined Documents

No preference for this. Most teams work this kind of thing out on their own over time. I’m not even sure what the factors are for deciding whether to combine documents or not. My preference is to keep documents short and focused. I find they are more likely to be read and used if they are concise and cohesive - maybe principles of good software module design could be pertinent in structuring documents too.

My preference is for diagrams surrounded by text. If a picture is worth a 1000 words, supporting text that explains the critical aspects of the diagram is a multiplier for this in terms of utility.

Respect Your Audience

Finally, and most importantly, when writing any software documentation consider your audience. Will the readers be coders? testers? domain experts? all of the above? Is this technical documentation, or business-facing documentation? How you answer these questions should factor strongly in terms of what kinds of information you include in the document, particularly how much technical detail you incorporate.

There’s probably a lot of things I’ve missed here. What has been your experience with doing DDD in terms of documentation?

Personal Kanban and Iterations, Day 5

Johanna Rothman — Fri, 03 May 2013 06:53:00 CDT

I am still making progress, although it’s more difficult to see my progress today. Why? Because I did not get as much to done.

One of my readers asked a question about the Urgent queue and the relative ranking of my ever-growing left hand column. How did I determine what to do, and what was the rank of each?

The Urgent queue always trumps everything on the left hand side of the list. I was so frantic on Monday, I didn’t order anything when I put the list together. It almost didn’t matter what I worked on, as long as I made enough progress to get enough things to done. As you can see, I did pick and choose. When I rewrite my list for next week, I will reconsider what I need to do in order. I need to complete the workshops and talks first. Then do the writing. My list next week should be shorter, so I should feel less frantic and be able to finish it.

As for the ones I have added to the bottom of the list, trumping the older ones in importance? No, not really. They are there because I realized I needed to do them also this week. My todos are getting away from me. Putting them on the list means I don’t lose them. I can relax because they are there. Now, I have to focus and do them.

If you are wondering, will I continue this series next week? No. I will not. One week of this is plenty. I wanted to show you a number of things:

Everyone has trouble every so often, with too much to do
The best way to organize your work is to see it, not matter what you decide to do next
I like personal kanban, where I finish one chunk of work and go on to the next
If you keep your chunks of work small, you can finish one and continue on to the next one. If your chunks of work are too large, you can’t finish anything and you are tempted to multitask. (Don’t do that!)

If you want to see all the posts in this series, here they are:

To see a “real” personal kanban board, the way I suggest you do it in Manage Your Job Search, go to Personal Kanban for Your Job Hunt.

Read my Book Review of Personal Kanban for more information on how to do it right. And, Gil Broza will be interviewing me for his Individuals and Interactions virtual training May 15, 2013. My topic? “Focus Keeps You Going.” Surprised? I don’t think so!

Personal Kanban and Iterations, Day 4

Johanna Rothman — Thu, 02 May 2013 07:55:00 CDT

I’m still chugging along, making great progress. I took some interruptions yesterday, as many people do. They are not reflected on my kanban. They are in my calendar, which I am not showing you :-)

A potential client emailed, asked for a call. I said yes, and we arranged for a call that day. Could I have put it on my kanban? Yes. Did I bother? No. Does that make me a bad person? No. It’s my kanban, not yours.

I don’t track metrics from my kanban. If I did, I would want that and the other calls there. But I don’t, so it’s fine.

I’m using my kanban to help me to get to done on my tasks, not to track my every piece of work. I’m using it to not forget work. I have a couple of phone calls this morning and a phone call this afternoon. I hope to complete one of the workshops today. Maybe.

I have a workout tomorrow and a number of phone calls, so I might not complete anything tomorrow. We will see. On the other hand, I am whittling down my list to something manageable. I no long feel anxious about it. I can see my progress. And, I have managed to blog this week. I am a happy, productive woman.

And, that is what personal kanban is all about.

London Workshops Almost Full, May 16 & 17, 2013

Johanna Rothman — Thu, 02 May 2013 07:45:00 CDT

Are you considering joining me in my Coaching or Project Management workshops in London on May 16 or May 17, 2013? If so, please decide quickly.

I have room for two more people in the coaching workshop. I have room for three more people in the project management workshop. When those places are gone, they are gone. That’s it, no more. I will run a waiting list.

If you are considering it because you are not sure, email me.

Personal Kanban and Iterations, Day 3

Johanna Rothman — Wed, 01 May 2013 10:08:00 CDT

I’ve been busy crossing work off my list. And, as with all of us busy people, I’m adding more work to my list. I feel as if I’ve accomplished a lot this week.

It’s just about time to rewrite my list, because with the cross-outs, it’s hard to see where I am. It’s time to go to draft 2 for the workshops, which might be the final drafts for the prose. I will be revising the simulations and interactions during the week. I hope to complete them by the end of the week. I do want to complete the workshops by the end of the week. I will feel more comfortable.

I had some items pop up on my urgent queue: I did go vote.

In yesterday’s post, there is a comment from Lukas, about how he likes rewriting his list, because he gets to reassess the relative rank of each item on the list when he rewrites the list.

If you use stickies, in a real personal kanban, such as I suggest in Manage Your Job Search, you pick up the stickies and put them down. Because you handle the stickies, you have a way of checking in with yourself to reassess the relative value of each item on your queue.

Okay, off to work again today. I’ll check in with you again tomorrow.

Personal Kanban and Iterations, Day 2

Johanna Rothman — Tue, 30 Apr 2013 07:08:00 CDT

I’ve made great progress on Day 1, and I wasn’t even in the office all day!

You can see I’ve added more todos, at the bottom of my queue. I discovered two urgent todo’s. I had a call-back, to reschedule a doctor’s appt this week to next week, and to vote today. (We have a primary election today for a special senate election in June.)

And, since I’m cheating on how to do a real personal kanban, I thought I would at least describe for you how to do real personal kanban over at Personal Kanban for Your Job Hunt.

You can see now there is a huge drawback to my list. I will have to rewrite my list, instead of just moving the stickies off. This is why in personal kanban, the right way is to not have a list. If you move the stickies, you don’t get this list nonsense, with lines crossed through.

Well, most people don’t have vertigo, either. So, tough. Okay, enough being meta today. On to the real work of the day.

If you missed part 1, here is the link: Personal Kanban and Iterations, Day 1.

Personal Kanban and Iterations, Day 1

Johanna Rothman — Mon, 29 Apr 2013 10:20:00 CDT

I use a form of personal kanban inside one-week iterations to finish my work and notice what I am not doing. I do this to maintain a cadence of blogging and to finish work. Did you notice that word, finish?

Sidebar: For those of you who don’t know what “kanban” is, it literally means “card.” It’s been used in manufacturing for years as a pull system for work. I have an example for what a kanban system might look like for teams in Agile Lifecycles for Geographically Distributed Teams, Part 3. I just realized I don’t have a picture of a personal kanban on Hiring Technical People. I will have to fix that.

I’m human, the same as you. I get bogged down. I sometimes get freaked out by the amount of work I have to complete. And, this week and next, as I complete my preparations for my London workshops and Let’s Test, I have more than I originally expected to do.

Why? Before PSL, several local potential clients called and wanted meetings. Meetings! Not phone calls, but in-person meetings.

The problem with in-person meetings is that they take longer. They aren’t one hour long. They are close to two hours long. I have to leave enough time to get there, have the meeting and get back. But, these are very interesting potential clients, so I took the meetings.

The result? I am not where I want to be with respect to my deliverables. So I will be blogging my personal kanban this week, so you can see what I do to finish my work.

Now, you can see from my picture, I don’t always do personal kanban “right.” I don’t have stickies. I have a list. That’s wrong. You’re supposed to do queues. Well, I don’t. This is my kanban. I can do anything I want with it.

Why don’t I use stickies? Because I don’t want to get up and move a sticky on a board. I get too dizzy. My desk is a disaster, so I don’t use a kanban notebook. it would get buried And, I don’t believe in tools. (Sorry, tool vendors.) I like paper and pen. I get total transparency this way. It’s easy for me to move things around.

I do schedule my longer-term article commitments to other people in the reminders tool on my Mac, so I don’t forget things.

I have a backlog in rough order of priority. Well, sort of. I have a ton of things to do before Wednesday, 5/1. Yes, everything down to “SQGNE presentation by 5/1″ is supposed to be done before 5/1. I can pick anything I want off that backlog and get it to done before 5/1.

Note that I have first drafts specified for the coaching workshop and the PM workshops. I have draft zeros done already. It’s time to finish the first drafts, and put them aside for another day or so. I already have draft one of the Sweden hiring workshop, which needs finishing, which is why it’s farther down on the list.

If people call and need something that does not go on the backlog, I have an urgent queue on the right side of the page. We’ll see how the week goes.

Remember, I’m only one person, so my WIP limit is one, which is why I didn’t even bother with a “Doing” column. I’m not going to have a PEN column this week. If I call anyone this week, it has to be after I get my todos done for my trip. I’m not taking interruptions. I have way too much work to do.

Oh, and I’m still working out at the gym, and sleeping my regular hours and eating properly. In order to accomplish everything I need to do, I have to take care of myself and maintain and sustainable pace.

Let me know if this is interesting to you. Yes, this blog post counts as my “MPD blog” entry.

Intro to Play Framework at Boulder Area Scala Enthusiasts

James Ward — Mon, 22 Apr 2013 11:36:00 CDT

This Wednesday (April 24, 2013) I’ll be presenting an Intro to Play Framework at the Boulder Area Scala Enthusiasts meetup. Also, Dustin Whitney will be presenting an Intro to Scala.

Hopefully see you in Boulder!

Management Myth 16: “I Know How Long the Work Should Take”

Johanna Rothman — Wed, 17 Apr 2013 06:48:00 CDT

Long ago, when I was a young developer at an anonymous company, one of my managers was disappointed with my progress. “I know how long the work should take. If I was doing the work, it would be done by now,” he huffed at me.

“Really?” I could have stopped there. I didn’t. “If you had done the work right the first time, I wouldn’t be in here mucking around with this, trying to fix everything. I pull something here, and something pops out over there. Of course, I’ve fixed nine defects by now, nine defects I hadn’t planned on fixing. Our customers are thrilled, because I’ve released the already-fixed defects. I just haven’t released this feature yet. But you would be done. Good to know. I wonder what else I have to clean up.”

Have I told you yet that I am the Queen of the Career-Limiting Conversation?

My boss didn’t fire me. At least not that week :-) It was a complex piece of code. I could have been more politic in my answer. But I was tired of pushing, pulling, and the puzzles. I wanted some straightforward puzzles to solve, not those roundabout problems. And then when he said he knew how long the work should take? That was insulting. As if I was taking my own sweet time with this. Ha! I was working hard. I was thinking hard.

This management myth is based on the belief that if the work is simple to describe, it’s easy and fast to do. Uh uh. Do not fall for that one.

Managers, architects, technical leads—anyone who has done work similar to this—can fall into this trap. This myth exposes several problems:

Does the manager understand the work as it stands, now?
Does the technical person understand the work now?
Do each of them agree on what done means for the work?

Having a snarky conversation as I did is not helpful. That’s why you should read my newly posted Management Myth 16: I Know How Long the Work Should Take. In that column, I provide you a useful example of how to have the conversation with your boss, as opposed to my example above.

If you are a manager and you don’t want to fall prey to these or other traps/myths, you should make it a point to participate in the Better Software/Agile Development conference in Las Vegas this year. I will be giving a talk, called Exploding Management Myths. I’m also leading a Management Lab. I hope you decide to join me there.

Start Your Agile Project Right and Coaching Master Class in London, May 16 and 17, 2013

Johanna Rothman — Fri, 12 Apr 2013 05:47:00 CDT

I am going to be in London, May 16 and 17, 2013. I am offering two interactive public workshops, one on starting your agile project right, and a master class on coaching. See the detailed syllabus and signup page for Starting Your Agile Project and Coaching Master Class here.

The syllabus for Starting Your Agile Project Right on May 16, 2013 is:

Introductions
Chartering a project (vision and release criteria)
Working with sponsors to define the tradeoffs
Iterations, kanban, or both?
Create boards for maximum transparency
What to measure
Wrap-up and summary

The syllabus for the Coaching Master Class on May 17, 2013 is:

Introductions
Simulation
What is coaching?
How to coach
Explore coaching stances
Implementing coaching
Wrap-up and summary

The workshops will be held in the Clerkenwell area of London. I expect to finalize the location within a day or so. I hope that if you are in the UK, you will join me. If you have questions, please email me.

Self Assessment Tool for Transitioning to Agile

Johanna Rothman — Thu, 11 Apr 2013 07:31:00 CDT

Over on agileconnection, a user asked about a self-assessment tool for measuring agile maturity. That’s not exactly the right question, because agile transition is a journey, not a destination. But, I can understand why he asked the question. I tried to be helpful. I supplied a set of questions to ask. Maybe you can go over there and add more to my list.

I still think the best question is this:

What benefit will you gain from learning this answer?

In any case, here are some questions I supplied to get the questioner (or you) started:

If you are doing iterations, are they four weeks or less? The answer should be yes. Many of us like one or two week iterations. Why? Because you get feedback more often rather than less often. And, you get to see working software.
Do you have demos at the end of each and every iteration? The answer should be yes. Why? To get the feedback from the customer/Product Owner.
Do you get every item in the backlog to done at the end of every iteration? The answer should be yes. For many teams on their journey, the answer is “not yet.” This does not make you bad, it makes you “on your journey.” You want to discover why.
Do you perform retrospectives at the end of each iteration to learn and inspect/adapt to improve your team’s agile process?
Do you look at your work in process and monitor that?
If you use iterations, do you measure your velocity with a burn up chart and make sure it does not look like a hockey stick?
If you are using kanban, do you measure your cycle time? Are you happy with your cycle time? (Did I just use a word that did not make sense to you :-)
Do you measure cumulative flow? (You want to make sure you do not have a lot of work in progress. It does not matter if you use iterations or kanban. This Matters to a team. It matters a lot.)

Gentle readers, do you have feedback for me on these questions?

I wrote Agile is Not for Everyone because I don’t believe in these assessments for agile maturity. However, just because I don’t believe in them is not going to make them go away. Maybe I can be more helpful.

Coding By Google

James Harmon — Wed, 03 Apr 2013 22:54:48 CDT

I almost named this post "I haven't written a line of code in years!" but that would not literally be true.

Actually I've written a lot of code, but probably as much (or more) has come to me through cut and paste from a Google search.

It struck me that what started as a helpful but infrequent technique to augment my work, has become the work itself. At first it was a line of code, then entire methods. But now GitHub (and SourceForge) have made the cloning of entire applications not only easy but allowable (and fun).

Not that there's anything wrong with that. Or is there?

I could spend the time to derive from first principals everything that I need to code, but why?
There is nothing new under the sun. All code has already been written.

And the code wants to be used. Coders themselves want their code to be used and re-used. It's why they post it. So there is no sin or crime committed.

But a new set of skills must be developed. Searching in the right way. Recognizing the good sources like StackOverflow and also recognizing the bad sources, like BigResource that just seem to aggregate StackOverflow posts but without the valuable rating system. Maybe we should be training developers in search and not in programming.

And where is the role of knowledge and memory? If we don't need to remember how to do anything - because we can look it up - then soon, we may be unable to remember, even when we wish to.

But it is just too useful to avoid. And so the term "Coding By Google" seems appropriate and even though I thought that I coined the term, turns out that this too is not new. Here's the earliest reference I could find.

bert's blog - from 2006

So go forth, code by Google, and be proud!

The command line is coming back - get ready

James Harmon — Sun, 31 Mar 2013 18:59:26 CDT

Recently I've rediscovered the command line and I'm really enjoying the improved productivity I'm getting. Also, I'm learning the tools that I work with better because I'm seeing the command directly rather than just picking menu items in Eclipse.

So I'm having more fun but it has also occured to me that now is the right time to start switching back to the command line. Let me explain.

Why is it named the "command" line? Because you give it commands. And how do you "give" commands (at least in non-computer situations). You say them.

We're now approaching the tipping point for voice recognition. It is generally excellent and one of the most obvious uses is to replace typing at the command line with voice commands.

It is harder to control a GUI IDE with voice commands but the command line is perfect for this approach.

So if you've been avoiding the use of the command line, or if it has been awhile, now is the time to brush up on those skills. I've been re-reading Neal Ford's excellent book "The Productive Programmer" which will help you get started. It is just as relevant now as it was in 2005.

I've also been very pleased with a new shell called zsh. Try it out.

Any downside? Developers will be constantly chatting to their computers as they work. Things could get a little noisy. Hopefully, this will spell the end of the "open pit" work environment.

Maybe now I can get an office with a door - that actually closes? And if we can't get offices? "Cone of Silence" anyone?

Dear Eclipse

James Harmon — Sun, 31 Mar 2013 18:59:00 CDT

Demand dropping for JavaScript skills

James Harmon — Sun, 31 Mar 2013 18:58:00 CDT

Of course, I'm biased, but I'm always looking for signs that the 2nd wave is ending. Just a reminder of how I define the waves -

Wave 1, The PC Age, 1980 - 1995, giant mainframes replaced by more agile desktops
Wave 2, The Internet Age, 1995 - 2010, connectivity rules the day
Wave 3, The Mobile Age, 2010 - 2025, all the computer you need right in your pocket

This article seems to be showing the end of the browser age. It will never go away but it also will never again be the dominant platform.

http://blogs.cio.com/it-skills/16835/hot-it-skills-2012

Telecommuting, Hoteling, and Managing Product Development

Johanna Rothman — Thu, 28 Mar 2013 10:14:00 CDT

There are two sides of this conversation about telecommuting: the employee side and the management side. I hope you stick around for both sides. You can yell at me at the end.

Employees: You Owe the Company a Full Day of Work

I’ve been thinking since Marissa Meyer’s announcement what I would say about the end of telecommuting at Yahoo!. Best Buy employees now have to have a conversation with their managers about how they will manage their telecommuting.

People who work remotely full-time have an obligation to their team-mates to be available, to make it easy for their team to find them. Once you have a telecommuter, you have a geographically distributed team, and anyone who’s been on one, knows the stresses that places on a team. It’s not impossible. It’s just harder on everyone.

I know the Bay Area has horrible traffic. I know the problems of being a parent and commuting to work. Mark and I managed those problems for more than 20 years, until our children graduated from high school. (Just because your children can drive does not mean you don’t worry about them. If they have mono in high school, you still worry about them. Yes, you do.)

And, I will tell you this: If you are camped out in the dining room or the living room on your computer and the kids are running around, or if you are driving the kids to their activities, you might be doing email, or you might be on the phone, but your work is not 100% on work. You are not focused. You cannot possibly be giving 100% of your brain to work. Some part of your brain is wondering what the kids are doing. Or, wondering why the kids got so quiet. Or, wondering why you can’t hear the dog anymore. This is not a full day of work.

If you work from home on a regular basis, and you regularly work from the dining room, I’ll say the truth: you are shortchanging the company. You are not delivering a full day of work.

Staying home when a child has a fever? Of course, you must. Staying home when a child has the mumps or measles or chickenpox? (Does anyone get these diseases now?) You must. You and your spouse can discuss/fight over who has to take time off. We did. You can, too. Good luck. That’s a marriage/career issue. I’m not getting into the middle of that one.

But the cost to the team of you not working with the team on a daily basis? That is so high. If you want to know, measure the value stream in your project.

Anyone can make telecommuting work. Especially if it’s just one or two days a week. But five days a week? No. That’s not reasonable for your teams. And, I wonder why you chose that. I bet some of you chose that because your company did not provide a reasonable environment for you.

Telecommute in an emergency? Of course. On a regular basis? Especially if you want agile teams? Craziness.

Once you have established teams, teams can create their own norms. But it takes many iterations and lots of trust to build those established norms.

Companies, You Owe Employes a Reasonable Work Environment

Once we get past the emergency days when parents must take time off from work, and have people back at work, what will we do with these people? We need reasonable work environments. Here’s what constitutes reasonable for me:

A team room for an agile team
Rooms for cross-functional teams to meet. (Even if you are not agile, you need rooms for cross-functional teams to meet. Yes, you do.)
An “office” for each person. It can be small if there is a team room.
Sufficient meeting space, so you do not have to go to buildings half a mile away for a meeting. Companies: Measure the time wasted trying to find a meeting room!
Enough bathrooms, so people like me don’t have to go to the men’s room, and shout “Woman incoming, there is no woman’s room on this floor.” (Don’t think I’m kidding. I’m not.)
Enough parking, close enough so people don’t have to wonder how long it will take them drive home, after they’ve hiked to their car
Lighted parking lots. Keep it safe, please.

There is more. That is the minimum. Think coffee, water, that kind of thing.

You know what’s missing from that list? The stupid “hotel” idea that companies thought they could get away with. “We don’t need a place for employees. They’ll plug in wherever they are, and that will be their place for the day.” The hoteling idea is total nonsense.

Well, that’s a way to make people feel as if they are welcomed, and part of a team. Not! This blog is called “Managing Product Development” for a reason. If you want to release products, you need teams. If you want teams of people to organize in some way, they need to know where to congregate. How the heck can they know where to congregate, if they have no place to sit?

“Hoteling” employees has to be just about the most stupid idea I ever heard. I don’t know who dreamed it up. Probably some architect who has a lovely office to sit in. Or an executive who has a permanent desk.

People need to know they are wanted. Do you want your employees? Give each of them a permanent space.

Oh, and don’t talk to me about introverts. Highly introverted people, who prefer to not talk to people, want to know where they will sit. They just don’t want to talk to more than one person while they sit there. Okay, some of them don’t even want to talk to one person, but they want a place to sit.

What Do You Need for Your Product Development?

Can you make telecommuting work for your organization? Of course you can. You can make geographically distributed teams work. I have a workshop on it, and I just published a paper on it. You are a smart person, working with smart people. The question is this: What will make your product development proceed faster, with more ease, with less cost, and allow you the most flexibility?

One of the reasons I urge my clients to transition to agile if they can, is that agile can provide them those benefits. However, agile is not for everyone. If they decide agile is not for them, we discuss if an iterative approach is best, or an incremental approach is best, or a combination is best. It’s all about what they need for their product development.

If you don’t need a geographically distributed organization, don’t create one. Telecommuting creates one. Instead, make it a policy that everyone come to work. Phase the policy in, as Meyer is. Have a conversation, as Best Buy is.

And, if you got sucked into those crazy workplace architectures, make enough offices/cubicles of large enough size, so that people have a place to put their stuff and work. Oh, and make the cube walls shorter, so people can see me coming, so I don’t have to wear a bike flag. That’s just craziness, too.

Talk With Your People

This is not about anti-parents. This is about bringing working people together for innovation and creativity. How do you solve the problem of long commutes, a reasonable workspace, and core hours?

The best thing you can do is talk about this issue with the people in your company. If you are a manager, don’t think you have all the answers. You might not even understand all the problems.

You don’t have to agree with me. I’m sure I will set off the mommy-wars and the daddy-wars, and the manager-wars, and the employee-wars. Well, I have on my flame-retardant suit. Go ahead. I’m ready! If you have the discussion in your organization about what is best for you, I have done a good job.

I look forward to a vigorous discussion.

Presenting Play Framework at Devoxx UK & FR 2013

James Ward — Tue, 26 Mar 2013 04:38:00 CDT

This week I’m at Devoxx UK and Devoxx FR presenting about Play Framework. Here are the sessions:

Tuesday March 26 @ Devoxx UK: Mobile Apps with HTML5 & Play Framework – With Nicolas Leroux
Wednesday March 27 @ Devoxx FR: 6 Minute Apps! Build Your First Modern Web App – With Nicolas Leroux
Thursday March 28 @ Devoxx FR: Play Framework vs. Grails Smackdown – With Matt Raible

It’s going to be an awesome week!

Intro to Play Framework This Week in Toronto, Ottawa, and Montreal

James Ward — Tue, 19 Mar 2013 10:07:00 CDT

This week I’ll be in Canada presenting an Introduction to Play Framework:

I’m looking forward to meeting our Scala northerly neighbors!