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