It's Surprisingly Hard To Outperform Markdown+Git or Google Sheets

General
1

Until recently, if I wanted to collaborate on a project, I’d create a Tracker backlog for it.
With Broadcom at the helm, that’s not really an option.
One of the reasons I started this site months ago was to start gathering and sharing a findable crossroads of experience with alternatives.

For small projects, I have been very surprised how hard it is to outperform two basic solutions:

  1. Markdown documents stored in a github repo.
  2. A Google Sheets spreadsheet.

When people imagine Pivotal Tracker’s competition, I think they usually imagine Trello, Jira, Linear, Shortcut, etc - other software explicitly trying to “manage products” or whatever.
Maybe they go so far as to include Github Projects.
I’m not sure that’s right; I think the actual competition for something like Tracker is, as with many pieces of niche software, cobbled-together workflows involving commodity broad-purpose document management solutions.

I’m mostly kicking this off now with the intent of extending it later, but in particular I have some almost “bullet journaling but for markdown in git” like approaches to doing Product Management type tasks through markdown files in a repo alongside the project they pertain to, and have collected some examples of spreadsheet usage that I think is worth documenting as a real pattern with upsides, downsides, and a sort of lifecycle.

2 Likes
2

One Pattern: Markdown + Github

For small projects, this pattern goes far. Especially early on, especially if you work with something that has a vim mode.

This gets you:

  • a crisp prioritized list with story state
  • an easy reprioritization workflow (dd/p in vim, for example)
  • an open and flexible format it's easy to extend/experiment with
  • clear history and attribution
  • distributed backups for free

I have experienced some disadvantages, and heard some complaints:

  • it can be hard to find for people who are not expecting to work in the repo
  • conversations and details are hard to both attach to backlog items and keep "out of the way"
  • The clarity of "theming"/"grouping" and "prioritization" are in tension, and in most projects this becomes mutually exclusive once the project gets going at all. (I recommend giving up theming to enable a single prioritized backlog, which I consider essential.)

The Basic Pattern

The simplest version is to add a backlog.md to your repo. If you like to keep the top level of your repo tidy, you might put it in a directory. I personally like ./texts for this.

In ./texts/backlog.md you can put something like this:

# To-do App Initial Implementation Backlog

_the working backlog we're starting with_

Sentence fragments can be read as starting with an implicit "I can..." and as having and implicit "... so I can..." at the end.
We think our understanding of who can and why is strong enough to get away with this for now, but we can fill them in if we think we should in any given case.

This _is_ in priority order, despite the "themeing."
It does not attempt to track bugs or chores.

## App Basics

- [x] There's a hello world that builds locally.
- [x] We can access said build on the internet.
  - https://app.example.com/
- [x] When we push commits, the internet instance updates.

## Basic To-do Items

- [x] make new items with editable string titles
- [x] add an editable textarea/text descriptions to items

## Basic Lists

- [x] make new lists
- [x] add existing items to lists
- [x] reorder items in a list by dragging and dropping
- [/] create new stories in a list from that list
- [-] persist reordering of items in lists through reloads (implicit AC)
- [ ] persist list and item information across deploys (implicit AC)
- [ ] remove stories from a list (item is _not_ deleted)

NOTE: At this point, we probably have enough to write a round of styling/visual
cleanup stories, and do some non-defaulting and landing page stuff.

The "list of checkboxes" pattern here renders in the Github UI.

  • Does it work in Discourse?
  • Yes it does.
  • [/] We use a slash / to indicate it's awaiting acceptance, and a dash - to indicate it's in flight.
  • [-] Unsupported state looks a little weird - but we use this to indicate "in progress" so an indent isn't bad!
  • this is just here to provide context for the formatting of the above lines.

Anyway, this works great as long as your themes are in order. The good news is that if you "do user story mapping" and "build a walking skeleton" you probably get sensible, ordered categories to start with. But you can see how it begins to break down at the end there. I added those (implicit AC) lines during acceptance. I happened to get lucky that the "top of the backlog" - the next thing on the list, the place where I wanted to insert my followup requests - was still "on theme." But what if I wanted to change the address the app was available at? It would be weird to add this under the heading of Basic Lists.

There's a second iteration of this that involves seperating theming from the backlog. I'll write about that next.

2 Likes