{"id":260,"date":"2021-01-15T19:38:04","date_gmt":"2021-01-15T19:38:04","guid":{"rendered":"https:\/\/blog.mozilla.org\/data\/?p=260"},"modified":"2021-01-15T19:38:04","modified_gmt":"2021-01-15T19:38:04","slug":"this-week-in-glean-proposals-for-asynchronous-design","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/data\/2021\/01\/15\/this-week-in-glean-proposals-for-asynchronous-design\/","title":{"rendered":"This Week in Glean: Proposals for Asynchronous Design"},"content":{"rendered":"

(\u201cThis Week in Glean\u201d is a series of blog posts that the Glean Team at Mozilla is using to try to communicate better about our work. They could be release notes, documentation, hopes, dreams, or whatever: so long as it is inspired by Glean. You can find an index of all TWiG posts online<\/a>.)<\/p>\n

At last count there are 14 proposals for Firefox on Glean, the effort that, last year, brought the Glean SDK to Firefox Desktop. What in the world is a small, scrappy team in a small, scrappy company like Mozilla doing wasting so much time with old-school Waterfall Model<\/a> overhead?!<\/p>\n

Because it\u2019s cheaper than the alternative.<\/p>\n

Design is crucial before tackling difficult technological problems that affect multiple teams. At the very least you\u2019re writing an API and you need to know what people want to do with it. So how do you get agreement? How do you reach the least bad design in the shortest time?<\/p>\n

We in the Data Org use a Proposal Process. It\u2019s a very lightweight thing. You write down in a (sigh) Google Doc what it is you\u2019re proposing (we have a snazzy template), attach it to a bug, then needinfo<\/a> folks who should look at it. They use Google Docs\u2019 commenting and suggested changes features to improve the proposal in small ways and discuss it, and use Bugzilla\u2019s comments and flags to provide overall feedback on the proposal itself (like, should it even exist) and to ensure they keep getting reminded to look at the proposal until the reviewer\u2019s done reviewing. All in all, it\u2019ll take a week or two of part-time effort to write the proposal, find the right people to review it, and then incorporate the feedback and consider it approved.<\/p>\n

(( Full disclosure, the parts involving Bugzilla are my spin on the Proposal Process. It just says you should get feedback, not how. ))<\/p>\n

Proposals vs Meetings<\/b><\/h3>\n

Why not use a meeting? Wouldn\u2019t that be faster?<\/p>\n

Think about who gets to review things in a meeting as a series of filters. First and foremost, only those who attend can review. I\u2019ve talked before about how distributed across the globe my org is<\/a>, and a lot of the proposals in Project FOG also needed feedback from subject matter experts across Mozilla as a whole (we are not jumping into the XPIDL swamp without a guide). No way could I find a space in all those calendars, assuming that any of them even overlap due to time zones.<\/p>\n

Secondly, with a defensive Proposer, feedback will be limited to those reviewers they can\u2019t overpower in a meeting. So if someone wants to voice a subtle flaw in the C++ Metrics API Design (like how I forgot to include any details about how to handle Labeled Metrics), they have to first get me to stop talking. And even though I\u2019m getting better at that (still a ways to go), if you are someone who doesn\u2019t feel comfortable providing feedback in a meeting (perhaps you\u2019re new and hesitant, or you only kinda know about the topic and are worried about looking foolish, or you are generally averse to speaking in front of others) it won\u2019t matter how quiet I am. The proposal won\u2019t be able to benefit from your input.<\/p>\n

Thirdly, some feedback can\u2019t be thought of in a meeting. There\u2019s a rough-and-readiness, an immediacy, to feedback in a meeting setting. You\u2019re thinking on your feet, even if the Proposal and meeting agenda are set well in advance. Some critiques need time to percolate, or additional critical voices to bounce off of. Meetings aren\u2019t great for that unless you can get everyone in a room for a day. Pandemic aside, when was the last time you all had that much time?<\/p>\n

Proposal documents are just so much more inclusive than design meetings. You probably still want to have a meeting for early prototyping with a small group of insiders, and another at the end to coax out any lingering doubts\u2026 but having the main review stages be done asynchronously to your reviewers\u2019 schedules allows you to include a wider variety of voices. You wouldn\u2019t feel comfortable asking a VP to an hour-long design meeting, but you might feel comfortable sending the doc in an email for visibility.<\/p>\n

Asynchronicity For You and Me<\/b><\/h3>\n

On top of being more inclusive, proposals are also more respectful. I don\u2019t know what your schedule is today. I don\u2019t know what life you\u2019re living. But I can safely assume that, unless you\u2019re on vacation, you\u2019ll have enough time between now and, say, next Friday to skim a doc and see if there\u2019s anything foolish in it you need to stop me from doing. Or think of someone else who I didn\u2019t think of who should really take a look.<\/p>\n

And by setting a feedback deadline, you the Proposer are setting yourself free. You\u2019ll be getting emails as feedback comes in. You\u2019ll be responding to questions, accepting and rejecting changes, and having short little chats. But you can handle that in bite sized chunks on your own schedule, asynchronously, and give yourself the freedom to schedule synchronous work and meetings in the meantime.<\/p>\n

Proposal Evolution<\/b><\/h3>\n

Name a Design that was implemented exactly as written. Go on, I\u2019ll wait.<\/p>\n

No? Can\u2019t think of one? Neither can I.<\/p>\n

Designs (and thus Proposals) are always incomplete. They can\u2019t take into consideration everything. They\u2019re necessarily at a higher level than the implementation. So in some way, the implementation is the evolution of the Design. But implementations lose the valuable information about Why and How that was so important to set down in the Design. When someone new comes to the project and asks you why we implemented it this way, will you have to rely on the foggy remembrance of oral organizational history? Or will you find some way of keeping an objective record?<\/p>\n

Only now have we started to develop the habit of indexing and archiving Proposals internally. That\u2019s how I know there\u2019s been fourteen Project FOG proposals (so far). But I don\u2019t think a dusty wiki is the correct place for them.<\/p>\n

I think, once accepted, Proposals should evolve into Documentation. Documentation is a Design adjusted by the realities encountered during implementation and maintained by users asking questions. Documentation is a living document explaining Why and How, kept in sync with the implementation\u2019s explanation of What.<\/p>\n

But Documentation is a discussion for another time. Reference Documentation vs User Guides vs Design Documentation vs Marketing Copy vs\u2026 so much variety, so little time. And I\u2019ve already written too much.<\/p>\n

:chutten<\/p>\n

(( This post is a syndicated version of the original<\/a>. ))<\/p>\n","protected":false},"excerpt":{"rendered":"

(\u201cThis Week in Glean\u201d is a series of blog posts that the Glean Team at Mozilla is using to try to communicate better about our work. They could be release … Read more<\/a><\/p>\n","protected":false},"author":1437,"featured_media":197,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[448297],"tags":[448297,103,448318],"coauthors":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/posts\/260"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/users\/1437"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/comments?post=260"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/posts\/260\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/media\/197"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/media?parent=260"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/categories?post=260"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/tags?post=260"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/blog.mozilla.org\/data\/wp-json\/wp\/v2\/coauthors?post=260"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}