Author: Bryan Morris

Emacs, org-mode, Kanban, Pomodoro… Oh my…

Posted on by Bryan Morris

This post is slightly off-topic of our usual AgileSoC theme; instead it is aimed at you Emacs folks who use org-mode and have been asking yourself “How can I combine Kanban and org-mode?”  Here’s how I did it.  It’s not rocket science, but it is very handy.

OK, I admit that I’m an Emacs geek.  I’ve used Emacs for a very long time, and have always been amazed at how many powerful, useful features are created for it.  The one feature that I’ve used for years is the org-mode.  org-mode is an organizer, note taker, outliner, planner,  etc.   Check out the web-site (orgmode.el).  It has so many features, I’m sure that I don’t know them all.

I use org-mode for three things:

  1. track my tasks;
  2. my time associated with each task, and
  3. a short journal of what I do every day (including any research).

All this information is located in one spot and org-mode allows me to keep it organized and easily searchable (it’s a text file).

Being an Agile-Emacs geek, I’ve been trying to use web-based and desktop systems keep track of my personal to-do lists using Kanban.  For the stuff I do I found Kanban provides me with the best way to track and report what I’m doing.  After being mildly impressed with many of these tools,  I never got into using them because they required me to get out of Emacs and get into a browser.  Using a GUI after being used to a straight text entry was also a little more trouble than I wanted.  Lastly, the data is usually in a proprietary format — that would be my data is now stuck in a proprietary format.

Being an Agile-Kanban-Emacs geek, my next step was to Google “emacs org-mode kanban”.  No luck.  What follows is my solution to creating a Kanban board using org-mode.

Kanban Board meet Org-mode Tables

org-mode provides an awesome table editing facility.  Once you’ve defined what the table looks like it automatically resizes the table to balance any new text you add.  My first step in creating my Personal Kanban board was to create a org-mode table.

Sad, Lonely, Empty Kanban Board

Initial view of Personal Kanban Board

My workflow (i.e., indicated in the header row) is pretty generic and straightforward:

  • Backlog (product stories not started yet);
  • Analysis (think, think, think);
  • Implementing (do, do, do);
  • Debugging/Testing (ensuring that it’s right); and finally
  • Done (proven correct and accepted).

Product Story meet Org-Mode Internal Links

Now I need to add my Product Stories to my backlog.  For this I use the org-mode markup language to add internal hyperlinks.  Links are created in org-mode using the format: `[[link]].  The target is simply: <<target>>.  Here’s a picture of my first Product Story added to the table.

My First Product Story in the Backlog

As you can see, org-mode has done several things:

  • readjusted the table to accommodate the new “Product Story 1” link in the Backlog column;
  • Translated my input of the link `[[Product Story 1]] to the `Product Story 1 hyperlink.  NOTE: If you click on this link with your mouse the cursor moves to the target line indicated by <<Product Story 1>>.

I use the org-mode tags :BACKLOG: and :STORY: so that I can filter on those for reporting, and I use the priority [#A] to indicate the importance of this story.

The next thing I do is add the sub-tasks that make up the Product Story and History to capture what the heck I did for each sub-task.

Adding the Details

I continue to add new Product Stories and sub-tasks as above, until I’ve got a decent size Backlog.

Initial Backlog

Now, I start working.  I’ll move Product Stories across my work flow, update history and complete actions.    Here’s a snapshot where I’ve done some work.

Work In Progress

OK, that picture is getting a little busy now, but the interesting elements are:

  • the Kanban board automatically re-sized as I moved the Product Story links from column to column;
  • I can use the org-mode folding capability (notice that <<Product Story 1>>  ends with ellipsis … i.e., “:BACKLOG:STORY:…” — the ellipsis indicates that some text has been folded, or is currently hidden from view.  Use the tab key when the cursor is on the line to toggle the fold/unfold);
  • I’m using the org-mode time-tracking feature to capture how much time I spend on each Product Story (captured in the lines indicated with CLOCK:).   org-mode has a way to generate a report summarizing the time spent on each Product Story.
  • There’s even an iPhone app (http://mobileorg.ncogni.to/) so that I can update my Personal Kanban board on my iPhone.  You can’t get sexier than an iPhone App; unless you’re not an Agile-Kanban-Emacs-iPhone geek. 😉

I’ve found it extremely easy to use Kanban and org-mode to capture and track my work.   If you’re a power org-mode user and can suggest other features of org-mode that would be useful in this context — I’d be all ears.

Pomodoro meet Emacs

Just to be clear.  I’ve been in management for over 15 years, and I pride myself in that I’ve never micro-managed anyone that I’ve supervised (for those of you who I have worked with, here’s your opportunity to contradict me).  However, I love to micro-manage myself.   I’ll break down any significant work until I have a set of tasks around 0.5 to 1.0 day in duration.   I need that for two reasons:

  • I’m too methodical (aka ‘anal-retentive’) to not capture a plan;
  • I have the attention span of a gnat.  If there’s a “bright shiny object”… I’ll be attracted to it.  Creating a set of a short sub-tasks means that I can progress toward the ultimate goal, and then as a reward take a break and go look at that bright shiny object for a bit, and then go onto the next task.

For the second issue of focus, I’ve been using the pomodoro technique for several months.  Go check out the web-site for more details on how to use this technique.  Again, I tried browser-based, desktop, and iPhone applications to track my pomodoros for me — but they were even worse than the Kanban applications I alluded to above for keeping me on track. As most of day is spent looking an Emacs screen — that’s where I need to be notified when a pomodoro is over.  Once again some kind Emacs elisp coder created pomodoro.el.  This allows me to start a pomodoro timer within Emacs; it automatically starts the short and long breaks and the next pomodoro; allows me to stop and rewind the pomodoro (for when I’m interrupted), and keeps a crude track of how many pomodoro’s I’ve completed.  Check out the elisp code for more details.

You may find using pomodoro will drive you nuts… or you may love it.  But if you’re an Agile-Kanban-Emacs-iPhone-Pomodoro geek, you’ll probably love it.

Happy tasking!

Agile Requirements: Are We There Yet? Part 1 of [Not Sure Yet]

Posted on by Bryan Morris

I’m at the start of a new project. We’re currently determining what features are needed in the end-product. This has led to me to thinking a lot lately about how to capture, prioritize and track the completion of these requirements as we progress through the project. Of course, I want to do this in an ‘agile’ way.

The typical agile method is to capture requirements in a set of high level “users stories”. User stories typically provide a concise way of describing what the system will do from the user’s perspective. Several templates of a user story exist; Mike Cohn’s being the one that I think is clear and concise:

As a <type of user>, I want <some goal> so that <some reason>”.

It captures the who, the what and the why of a feature – providing some essential context to the assist in the implementation, validation and acceptance of a feature.

User stories are then typically split into progressively smaller use-cases, or tasks until you establish a firm understanding of what the feature is supposed to do, and how your team is going to complete the functionality as the user expects.

I found Cohn’s template particularly effective when creating some tool or script that I needed to create because it is much easier to comprehend than a typical requirement statement of “The system shall….”.

But… if there’s one aspect of agile that I really think is difficult to translate into an ASIC/FPGA world, it’s the concept of user story. Perhaps it’s because I simply don’t have the experience in writing user stories. But I think it has more to do with my trouble in writing an ASIC story from a user’s perspective. In many cases, a feature does not even provide any meaningful output that is visible to the user e.g., some esoteric standards requirement about how an interface must be defined.

Then serendipity came through for me, when my former colleague and AgileSoC collaborator Neil Johnson was in town on vacation and wanted to grab a beer. He knew James Grenning , who happened to be in Ottawa at the same time to deliver some training, and invited him along too. I’ll cut it short by saying I had a very intersting conversation with James and Neil. You see James is an expert in Test Driven Development for embedded systems. In fact, he’s written a book on the topic Test Driven Development for Embedded C. It was very interesting to discover the similarities that exist between embedded system design and SoC development. Including the perceived and real barriers to adopting an agile flow in an embedded design.

To cut to the chase, we got to talking about user stories and how they don’t really fit into the ASIC development, when James suggested that he calls user stories “Product Stories” instead. While its a simple semantic change of “user” to “product”, for me it was a lightbulb moment. It helped me identify the issue I’ve been having with ‘user stories’: I’m not implementing something for an end-user; I’m developing a product that will fit into a larger system that will ulimately be seen by a user.

Like User Stories, Product Stories are intended to be very high level descriptions of the features that you want to develop along with the acceptance testing that proves the feature is what you expect.  The key is that these are short descriptions from the system’s perspective. Instead of the who, what and why as in a user story the product story for ASIC development should include the where,what and why. Specifically, a good requirement contains the following elements:

Behaviour: (the what) A short descriptive story explaining the behaviour at a high level.
Justification: (the why) Some idea on why this is important to the system (unless it’s absolutely clear e.g., some standard protocol);
Context: (the where) Where in the system this feature is needed
Acceptance: simple set of acceptance tests to prove that behaviour is correct.

I’ve been developing the following template, that I’ll be considering to use for my Product Stories, which is similar to the ‘user story’ template above.

“The <context> needs to <do some behaviour> so that <some reason> “.

A product story provides some clear guidelines on the functionality expected, as well as a clear indication of what coverage points must be captured before you declare the product story complete. In fact, I think it might be a good idea to stating these acceptance criteria as functional coverage points.

As I work through these concepts in my head, I’ll attempt to describe them in in my next few blog posts.  I’ll talk about how I see these Product Stories being created, developed and tracked in an AgileSoC world.

I’d welcome any comments on this post, and especially how you are doing your requirements management – especially when requirements are very fluid (which, I’m guessing, is probably most of the time for most of us :-)).