From: dbucklin@sdf.org
Date: 2018-11-30
Subject: Turning the Wheel
Reading this HBR article[1] reminded me that although so much of
what I do is computer-assisted, the fundamental task of keeping
things moving, what I call *turning the wheel*, is a practice that
requires discipline. And some tools.
Here are the tools and practices I use. I take a lot of inspira-
tion from Plaintext Productivity[2] and GTD[3], but my process is
constantly evolving. I do most of my work in Vim[4] and I use
awk[5], sed[6], and other GNU coreutils for text processing, gener-
ating reports, and the like. I've written more about these and
other tools in Casual Programming at Work for Fun and Profit[7].
To-Do List
A to-do list is the bedrock of a personal productivity system. If
you do only one thing, get in the habit of maintaining a to-do
list. This is a place to keep the list of next actions I need to
take. Once something is done, it gets removed from the to-do list.
Each to-do item should include a few words of description, at
least. A to-do item might also have a due date or be associated
with a project.
Make sure your to-dos are things you can actually get done. It
might sound obvious, but it doesn't happen automatically. There
are frameworks, like the SMART criteria[8] to help you set yourself
up for success.
To-Do List Format
I use the todotxt[9] format. It strikes a balance between human-
usability and legibility to text-processing tools. This format
provides conventions for associating metadata to to-do items, like
due dates and projects. I also keep my list prioritized, with the
most important items at the top.
Example:
xSend out sprint review summary
Update process docs with QA process changes due:2018-12-01
Follow up with SK re retailer locator testing due:2018-12-05 +locator
To-Do List Tools
Vim mappings:
Move a line up: `nnoremap _ :m .-2<cr>`
Move a line down: `nnoremap - :m .+1<cr>`
Mark an item complete: `nnoremap <leader>x Ix<esc>j`
Move completed items to the end of the list: `nnoremap <leader>e
:g/^x/m$<cr>gg`
To archive completed items before deleting them (usually used with
a range): `:w >> done.txt`
The `monday` script:
This script takes the content of the weekly file and inserts it in-
to my to-do list. I have a header on my to-do list, so this script
inserts the weekly items below that. I just run `:!monday` in Vim.
#!/usr/bin/env bash
sed -i -e '3r weekly' todo.txt
Project List
This is a list of high-level initiatives that the organization is
working on. I keep this list separate from my to-do list because I
may not have any to-dos for an active project, but that doesn't
mean that the project is over. Each project should include a few
words of description, the name of the project's owner -- the deci-
sion-maker, and other stakeholders (consider a RACI for large
groups). Identify a next action for each project. Optionally, you
could keep a project journal that summarizes project events and
changes.
Project List Format
How you structure this document depends a lot on how you intend to
use it. For example, I'm currently using an Excel spreadsheet that
is stored in SharePoint. At minimum, it should be a list of high-
level initiatives that are likely to have an impact on your work.
My text-only format uses key-value pairs on each line within a
project, separated by a colon. Projects are separated from each
other by a blank line. This format is inspired by GNU Recutils[10]
and is easy to edit and easy to process with text-processing tools.
Example:
Name: Retailer Locator
Owner: DB
Target Date: 2019-02-15
Next Action: Feasibility assessment by SK expected 12/7
Name: New Campaign Templates
Owner: GG
Target Date: 2019-01-15
Next Action: Meeting to define templates 12/21
You could augment this with single-line, time-stamped journal en-
tries that record project progress. Just remember to separate
projects with a blank line.
Project List Tools
This awk script creates a report from a file in the above format.
BEGIN {FS=": "; OFS="\t"; idx=1}
/^Name: / {name = $2}
/^Target Date: / {date = $2}
/^Next Action: / {action = $2}
/^$/ {
print name, date, action;
date = name = action = "";
}
We can sort the results by date using `sort`.
awk -f script.awk <projects.txt | sort -k2
Imagine beefing this up with HTML. You could also format it using
markdown and then run it through Pandoc to create HTML or a Word
document. You could also output it in some value-separated format
and open it up in Excel.
Meetings
Have an agenda for every meeting and send it out to everyone before
the meeting. An agenda sets the stage for the meeting, allows peo-
ple to come prepared, and saves time by organizing the conversa-
tion. During a meeting, I try to capture as much relevant informa-
tion as possible. I use the one-sentence-per-line[11] method to
keep capture simple.
At the end of the meeting, identify next steps along with their
owners and target dates. Unless the project is over, you should
also establish a target date for the next meeting; any active
project should have a future meeting scheduled.
After the meeting, I clean up my notes and send them to all meeting
attendees as well as other project stakeholders that may not have
been at the meeting. Using the one-sentence-per-line method helps
me produce, with some editing, a list of easy-to-read bullet
points. This process usually includes adding several items to my
to-do list. Sending these notes out should also prompt others to
update their to-do lists in case they didn't do so during the meet-
ing. Consider including the meeting notes with the agenda for the
next meeting.
Notes
I take notes at almost every meeting I attend. I'll also use my
notes file to prepare memos and to organize information (e.g. sum-
marizing email threads). I insert a date and time whenever I add
new notes. This is incredibly useful when correlating my notes
with other artifacts such as past meetings or emails.
Notes Tools
I have one Vim mapping that is critical: it inserts a timestamp at
the beginning of the current line and puts Vim in insert mode after
it. After I insert the timestamp, I add a few words that capture
the meeting topic. I use this same mapping in my journal.
nnoremap gs :pu! =strftime('%Y-%m-%d %H:%M')<cr>A<space>
I also have a trick in Vim for pulling out to-do items. I've found
that when I recognize a to-do item, whether it's mine or someone
else's, I tend to use the word "need" on the line. This might look
like, "Jane needs to confirm timing with sales" or "I need to send
out the updated timeline." These lines are usually intermixed with
all my other notes, and it would be nice to be able to quickly pull
them out into their own list.
First, I need to select my notes. If there are no linebreaks with-
in my notes, I can just use `vip` to select the text. I could also
use `v{` assuming I'm at the end of the paragraph. Another option
is to put the cursor on the line below the last line of notes and
use `v?^2` to select backward to the previous timestamp.
With my notes selected, I can use `g` to find the lines with the
word "need" in them and then `t` to copy those lines to the end of
the file.
:'<,'>g/[Nn]eed/t$
Reports
I send out unsolicited reports with information that has proven to
be useful. Examples include:
* Project status with next action and target date for each active project.
* A weekly list of the user stories added in the last 7 days.
* User stories that are about to go into production.
* Top backlog items.
Every Monday, I add all of these to my to-do list. Most of these
come right out of Azure DevOps. For status reports, I start with
the simple PPP method[12] and scale up from there as needed. A
similar strategy can be used with process documentation to promote
awareness.
Formatting Reports
I compose and edit using plain text or markdown in Vim. For meet-
ing agendas and notes, this is often sufficient. If I need to add
some rich formatting, I use Pandoc to convert markdown into HTML or
a Word document. Then I will either copy and paste into Outlook or
attach the document to an email.
Using Pandoc to create standalone HTML documents is quite powerful.
In addition to using custom CSS, I've embedded Google Charts[13]
into HTML documents.
Charts
I generally use DOT and GraphViz (via plantuml.com or plant-
text.com) to create charts. I've used LucidChart and Visio in the
past and they are great tools, but I don't particularly enjoy push-
ing pixels and using DOT lets me focus on the data. I've written
about this in Diagrams from Text with PlantUML[14]. See
http://www.tonyballantyne.com/graphs.html[15] for many more exam-
ples. Google Charts[16] is another good option for quantitative
charts that can be embedded into HTML documents.
Example: Org Chart
Creating an org chart helps me learn people's names and also helps
me understand their responsibilities in the organization. Using
DOT, I can denote formal relationships with a solid line and infor-
mal relationships with a dotted line. I also try to develop a
shorthand, usually a person's initials, to reference them in notes.
@startuml
digraph Org {
rankdir=BT
"Juan B" -> "Don EV"
"Gustavo F" -> "Juan B"
"Hector S" -> "Juan B"
"Walter W" -> "Gustavo F"
"Mike E" -> "Gustavo F"
"Jesse P" -> "Walter W"
"Skinny Pete" -> "Jesse P"
"Gale B" -> "Gustavo F"
"Brendan M" -> "Jesse P"
"Tuco S" -> "Hector S"
"Ignacio V" -> "Tuco S"
"Christian O" -> "Jesse P"
"Leonel S" -> "Hector S"
"Marco S" -> "Hector S"
"Tyrus K" -> "Mike E"
"Victor" -> "Mike E"
"Chris M" -> "Mike E"
"Lalo S" -> "Hector S"
"Gonzo" -> "Tuco S"
"No Doze" -> "Tuco S"
{rank=same;"Gustavo F" "Hector S"}
{rank=same;"Walter W" "Mike E" "Gale B" "Tuco S" "Leonel S" "Marco S" "Lalo S"}
{rank=same;"Brendan M" "Skinny Pete" "Christian O"}
}
@enduml
Here, too, it would be good to put a date on the org chart. Orga-
nizations change over time, and it could be valuable to be able to
look back at how it was structured in the past. Since this is
text-based, version control tools can be used to analyze changes
over time.
Process Charts
Just as personal discipline is important to keep things running
smoothly at your desk, group discipline helps avoid problems within
a team. Having a visual aid helps team members internalize a com-
mon understanding of the ideal process and their place in it. I'll
usually create a detailed description of the process, and then cre-
ate a chart that summarizes the written information. PERT and
Gantt charts are useful for depicting dependencies within a
process.
Example:
The following chart summarizes the flow of backlog items from their
initial entry into the backlog through to completion. This should
be accompanied by a document that describes the entry and/or exit
criteria for each state.
@startuml
digraph P {
rankdir=LR
New -> Approved
Approved -> Active
Active -> "QA Ready"
"QA Ready" -> "QA Pass"
"QA Ready" -> "QA Fail"
"QA Fail" -> Active
"QA Pass" -> "Move to Prod"
"Move to Prod" -> Closed
}
@enduml
Review
Reviewing all of this information on a regular basis is key to
turning the wheel. Make time to review all of this information on
a regular basis. Several times a day in the case of the to-do
list. Daily for the project list. At least every one or two weeks
for things like the process documentation. In each case, look over
the information and ask yourself, "Is this accurate? Could this be
improved? Is there something I can do to move this along?"
Journal
I keep a journal because not everything I do hits my to-do list. I
think it's useful to know what I've been doing -- if not for my own
sake, then in the event that someone asks. I keep my journal in a
regular, one-entry-per-line format. This helps me use text pro-
cessing tools to help me fill out timesheets[17] and create status
reports. That said, I don't use my journal to track how much time
I've spent on something nor to determine whether or not I've done a
particular thing in the past.
Example:
2018-12-01 20:27 Wrap up post about tools and methods.
2018-12-01 19:54 Create process digraph.
2018-12-01 18:45 Research Breaking Bad characters. Create cartel digraph.
2018-12-01 07:23 Write example awk script for project reporting.
2018-12-01 06:37 Add to-do list Vim mappings to tools and methods article.
2018-11-30 18:27 Add notes Vim mappings to tools and methods article.
2018-11-30 17:17 Develop tools and methods article.
Journal Tools
See the section on summarizing[18] in my journal-to-timesheet post.
Summary
These tools and methods create a framework for capturing, analyz-
ing, organizing, and disseminating information. They create a
platform for the creation of a variety of information products in-
cluding reference documentation, decision support memoranda, and
status reports. By reviewing this information regularly, we can
drive action and maintain momentum within and beyond our immediate
team.
+--------------+---------------------------------------------------+
|Tool | Purpose |
+--------------+---------------------------------------------------+
|To-Do List | Specific, near-term things I need to do. |
+--------------+---------------------------------------------------+
|Project List | High-level initiatives that drive action. |
+--------------+---------------------------------------------------+
|Meetings | Conversations that establish next actions for |
| | projects. |
+--------------+---------------------------------------------------+
|Notes | A place to capture and organize incoming informa- |
| | tion. |
+--------------+---------------------------------------------------+
|Reports | Information published for stakeholders to use. |
+--------------+---------------------------------------------------+
|Charts | Visualizations of information. Often used in re- |
| | ports. |
+--------------+---------------------------------------------------+
|Review | An effort to continuously improve information |
| | products and processes. |
+--------------+---------------------------------------------------+
|Journal | A log of events and actions. |
+--------------+---------------------------------------------------+
References
[1]: https://hbr.org/2015/11/two-things-to-do-after-every-meeting
[2]: https://plaintext-productivity.net/
[3]: https://gettingthingsdone.com/
[4]: https://www.vim.org/
[5]: https://www.gnu.org/software/gawk/
[6]: https://www.gnu.org/software/sed/
[7]: /work/2018/09/27/casual-programming.html
[8]: https://en.wikipedia.org/wiki/SMART_criteria
[9]: http://todotxt.org/
[10]: https://www.gnu.org/software/recutils/
[11]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
[12]: https://weekdone.com/resources/plans-progress-problems
[13]: https://developers.google.com/chart/
[14]: /work/2017/09/11/diagrams-from-text-with-plantuml.html
[15]: http://www.tonyballantyne.com/graphs.html
[16]: https://developers.google.com/chart/
[17]: /play/2017/11/10/journal-to-timesheet.html
[18]: /play/2017/11/10/journal-to-timesheet.html#summarizing