proposal: Freeze OKRs in Markdown for easy long term access

[daviddias]

I've the feeling that the OKRs fall into oblivion once the Quarter Passes and the spreadsheets are never opened again. Yet, they tell a story about the progress of the project, they inform what was achieved, how much and what was left behind.

In another hand, we have the Community WG experiment on capturing them in Markdown https://github.com/ipfs/community/blob/master/okrs/2019-q1.md.

I want to propose for us to freeze our OKRs in Markdown format in the docs that we already have at https://github.com/ipfs/team-mgmt/tree/master/OKR. It would give us a easy scroll view across the quarters and enable changes be more explicit.

[daviddias]

@momack2 any thoughts?

[andrew]

I’ve been recording the package manager related OKRs in a GitHub issues with an OKR label for filtering, it’s been helpful for looking back.

[warpfork]

(may or may not be the issue for this, but, tangentially relatedly, because it's something that Doesn't Happen in a spreadsheet --)

Something I find concerning about OKRs is the degree to which they don't help us capture other things that happen in a quarter; and thus, how much OKRs don't guide themselves in a self-improvement loop. Lack of connected process for annotating OKRs with other happenings in the quarter also means they can tell a very incomplete, potentially even misleading, picture of was achieved and what was left behind.

I've been considering attaching a block of text to the quarter-end OKR scores (in the github document -- we already do that in the IPLD team as well; and it's important it's in the same document so it can't be misplaced or skipped by over-focused linking) that does a brief retro that lists:

• things we didn't capture but accomplished (and couldn't have expected)
• things we didn't capture but accomplished (and could have expected)
• things we didn't capture up front but became asks/wishes, and weren't done

The first one is for understanding how much difficulty we're having with OKRs as a flow we're because we're interrupt driven, or are working on tasks which themselves involve discovery.

The second one will often shake out things that are simply more granular progress towards our listed goals -- which is good for some positivity, good for real status and progress reporting to above, and just good exercise for getting us to consider breaking things down in the future. Or, other kinds of stuff in group two might indicate other issues in our flow of soliciting and selecting OKRs in the first place.

The third is the least essential and interesting (and maybe could be elided), but is there to keep things in that category from getting shoehorned into the other two, and it also provides a more complete picture for "what was left behind". A longer list here might actually be considered an indication that we're doing well at OKRs and sticking-to-it; or might provide some other interesting insight.

---

I'm not sure these are the only or the exact correct questions, and I acknowledge at some point we want to wrap things up into numbers that are spreadsheet-friendly for sheer simplicity of aggregate presentation -- but it does simultaneously seem like we need more information to diffuse both in and out of this process in general, and I wonder if this would help.

[warpfork]

(I'm just hands-down 👍 👍 👍 👍 💯 💯 💯 💯 🚀 🚀 🚀 for freezing things out of collaborative editors when they're done being edited, and into git+markdown is a great way to do it -- sorry for zooming by that and into other/deeper weeds.)

[daviddias]

Quick comment on @warpfork comment so that it doesn't fall into oblivion. That said, let's please keep the issue on the topic: i.e. freeze or not freeze the OKRs in markdown :)

Thank you so much for sharing your experience @warpfork. My diagnosis is that the symptom you described is a result from a half adopted OKR process. Note the documentation on OKRs -- https://github.com/ipfs/team-mgmt/tree/master/OKR#notes-on-okr-planning --, specially the Async Retrospective part -- https://github.com/ipfs/team-mgmt/tree/master/OKR#async-retrospective-of-the-quarter --, which is where some of the Working Groups (the ones that fully embraced the planning cycle) have been capturing and celebrating all of those extra planned achievements.

---

Now back on the topic

@andrew The freezing on issues is also interesting, specially thanks to Github's linkability features.

I've overall have a feeling of tool creeping. With each new tool, new domains, accounts and different search engines and indexes that we have to use, the less discoverable and clear our information seems to be.

It is known the lore of having specific tools for each job, but when you need to climb a giant mountain, having tools that are multi-functional and that do only the necessary and nothing more (therefore removing complexity, weight and overhead) the simpler the journey up will be (or sometimes, the difference is either it is possible or ☠️)

[warpfork]

+1 text files in git as preferable to github issues.

(Github issues may have a tagging system, but I don't know what I'd use that for I couldn't just use a directory for, and they carry a whole bunch of other semantics that are baggage that seems counterproductive: e.g. open/closed? What would that... mean? Do we want comment threads to be on by default on the "freezed" document? Etc.)

[mikeal]

I wrote a little Vue.js demo like 9 months ago that did some cool stuff with OKR’s in markdown files in a repo. It was designed to pull in OKR’s from several repos and show them together, and also to pull the recent activity of any linked issues into one dashboard view. The idea behind this was that the OKR’s could provides links that informed a view of all activity.

I never had the time to finish it, but it’s worth noting that you can do all of this without a real backend. As long as you can have people login with GitHub and use that token, you can get the markdown files and pull data from the issue APIs all in the browser via CORS.

[momack2]

Very supportive of this as long as it is useful and doesn't add busywork. I think the easiest thing would be to use a quick AppsScript that exports from google sheets and into markdown. Seems most likely to give flexibility and still gives us all the scripting/weighting power we love in sheets.

Here's an example of "MarkdownTableMaker" on an empty OKR sheet:

	Priority Level	Mid-Q Actual	Mid-Q Projection	Q4	Notes on writing
Total Score	P0-4	0.3	0.6	0.6
Objective #2
Key Result #1	P2
Key Result #2	P2
Key Result #3	P3

I'd be happy to replace our current end of quarter finalization step with running this add-on and inserting this in our existing OKR markdown files for the quarter in question. Doing that export at the beginning of quarter and then overwriting with the right grades at EOQ also works for me - but I think we need to continue using the sheet as the place to grade / add notes until the quarter is past.