Add concisely to handbook and link from new team member onboarding: "Why this way?"

[mikermcneil]

How?

• [x] Add concisely to handbook (“company” page- maybe under “culture”? Up to you)
• [x] link to it from new team member onboarding
• [x] Schedule time with the people who haven't done the latest onboarding and share these ideas with them, going through it all in the handbook with them (we can split that up amongst the digital experience team)
  • the people from this doc: https://docs.google.com/document/d/1nhri7VrmpuZlYCY4emkfJJgpqy13KXm8e0_R_kjqUrk/edit

What?

i.e. terse philosophy and minimally viable explanation for each of these things so that everyone is 100% in sync on what they are and the reason why:

• [ ] why wireframe-first?
  • at Fleet, we call this “drafting”
  • drafting happens on a per-change basis. Doing drafting does not mean the associated product changes can’t be iterative. Product changes are small whenever possible, to deliver value quickly. But each small, little change gets drafted first. Tldr; Drafting == “product design, as a devops stage”
  • you get to throw away the wireframes: whereas coding before designs and verbiage have been thought through and iterated on several times can result in artifacts in the code that never get cleaned up, and lead to initial coding decisions quickly becoming out of date as the inevitable iterations happen (just more slowly, in code, rather than in wireframes or usage drafts). Over time, this adds complexity that is time-consuming to clean up, slows down development, and can even result in bugs. It can lead to mismatched code and naming decisions that are confusing, especially for new contributors. It can be painful for the people doing all those code changes (most of which could have been realized and iterated on much earlier, during wireframing)
  • UI and API error messages designed on the fly while coding: This on-the-fly designing has to get squeezed in amidst getting the actual underlying feature to work, which requires attention and a lot of focus. It takes time to shift focus and dribble with error messages and designs… and then when you take the time, you inevitably want to tweak them, which now has to happen in code, rather than wireframes.
  • Testing and reading error messages can be easily missed during human quality assurance, meaning that they may never get read carefully and considered from a UX perspective by anyone else either, other than maybe the other person doing the code review, who was likely time-strapped and focusing on catching potential coding issues and missed edge cases, rather than reading error messages out loud for clarity and simplicity, comparing with other error messages in the product for consistency, rereading, and then iterating on them several times
  • iterating in wireframes first lets us do all this, not just for error messages, but for layouts, flows, interactions, help text, button text, forms, URLs, API parameters, API response data, and more. It lets us think more deeply about (and rapidly tweak) the userland journey that people using Fleet’s UI, API, or CLI are experiencing. It lets us role play as the user and tweak, then role play again, then tweak again, then role play again, etc; many times. Then, when the initial drafter is happy with a change, they do a feedback cycle, which is basically the same thing but with another person carefully reviewing the wireframes, gnashing their teeth, muttering about pros and cons and edge cases, then providing suggestions and revisions. Then that whole process can repeat, sometimes 2-3 more times.
  • editing wireframes is way faster, easier, and more accessible to people who are not code-literate than it would be to prototype in code. Prototyping using wireframes allows more people to participate, and it leads to more informed decision-making, with faster iteration and less sunk-cost fallacy
  • you can show wireframes to people and they're almost as good as a demo, in terms of understanding how something works.
  • Figma allows us to create wireframes that are higher-fidelity without costing any more work, because we can copy and paste UI components from other places and just reuse them quickly (rather than a lofi wireframing system like Balsamiq, or a fat marker sketch on a piece of paper)
  • everyone can contribute: anyone can suggest wireframes (at any level of fidelity) and propose ideas at product huddles; not just the “official” product team. Since everyone can contribute to what goes into the product, even contributors from outside the company can bring wireframes to the huddle and participate in the feedback and revision process. Product is responsible for prioritizing what gets worked on and synthesizing the right requirements, not for coming up with all the product ideas.
  • Userland-first: This concept extends beyond just graphical user interface wireframes (annotated pictures of what users see on their screen): it’s not just for UI, but also fleetctl and the REST API. Start with usage. Begin by defining the interface— the way something new will be used, or how usage will change— then build to that spec. This works great for:
  • APIs
  • config settings
  • CLI options
  • even business processes (eg designing an expense policy, or a new onboarding process for humans)
• [ ] why monorepo?
  • Everything is all in one github repo, no exceptions (except for the confidential repo -- and the only reason it's a separate repo is because github doesn't allow you to have confidential issues within a public repo)
  • More repos == more surface area == more things that have names that people have to remember. Things can get lost. All of the pieces of the project are more visible and accessible to the community when they are in one place.
  • Fewer repos pools GitHub stars, which more accurately reflects the true level of popularity (instead of diluting it across multiple repos)
  • With only one repo, you can consolidate your automation and labels. Otherwise, you have to manage labels and automation across multiple repos, which can drift.
• [ ] why organize work in team-based kanban boards?
  • It is helpful to have a shared framework for how every team works, plans, and requests things of each other. Fleet's kanban boards are that framework. 3 goals:
  • intake: give people from anywhere in the company or the world the ability to request something of a particular team (i.e. add it to their backlog)
  • planning: give the team's manager and other team members a way to plan the next 3 week iteration of what the team is working on, in a world (the board) where the team has ownership and feels confident making changes
  • shared todo list: what should I work on next? Who needs help? What important work is still blocked? Is that bug fix merged yet? When will it be released? When will that new feature ship? What did I do yesterday?
  • Visibility: Everyone in the company knows where to look to see what's on a particular team's plate, the status of the work, whether it's complete, and if there's any way they can help. Every kanban board is associated with a particular team or department in the org chart; based around people moreso than categories of work.
• [ ] why 3 week cadence?
  • Alignment: the Fleet product is released every three weeks. Using the same 3 week cadence gets everyone at the company on the same schedule, doing planning around the same time
  • Awareness of releases: This gives team members who might not be directly involved in coding or releasing the core product awareness of what version we're on currently, and when the next release is shipping
  • GitLab has been on a monthly cadence for the better part of 10 years, to great effect
  • 3 weeks is quicker than 4 weeks
  • Answers "when do we need to get this done by?" in a default way: by the end of the iteration (every documented issue is part of a 3 week iteration cycle)
  • Side note: here "Iteration" === "sprint" === "cycle" === 3 weeks according to plan
• [ ] why agile?
  • Just the manifesto: https://agilemanifesto.org/ — not religious adherence to any kind of bespoke way of doing agile
  • releasing software iteratively results in it actually working, gets it into the hands of users faster, and makes contributors fitter, happier, more productive
• [ ] values and mission
  • This stuff: https://fleetdm.com/handbook/company
  • this one's already written in the handbook
• [ ] why the emphasis on training?
  • investing in people: generous, prioritized training, especially up front, helps contributors understand what is going on, a prerequisite of helping people feel confident and make better decisions at work
  • especially for people who may feel like outsiders to the osquery (/security / startup / IT) space
  • but even insiders want to understand how to fit in and provide value quickly in the particular culture of the team
  • sharp focus on training means things are written down, which leads us to…
• [ ] handbook-first strategy
  • this idea comes from GitLab - be sure and link to the excellent explanation in their handbook (find the shortest simplest one)
  • plus: writing things down and keeping them up to date keeps everyone believing that the Fleet community is a place where things are correctly documented, accurate, and clean… so they keep it that way by default (the “New York Subway” effect). For example, once a room gets messy and stays that way for a while, most people get used to it: they stop noticing the mess, and it gets harder to justify trying to clean up the mess (eg. subconscious: “This is a place where documentation doesn’t seem to always be up to date, therefore I feel discouraged and socially pressured away from spending time on keeping the documentation up to date.”)
• [ ] why not continuously generate REST API docs from javadoc-style code comments?
  • Generated documentation via tools like Swagger/OpenAPI it has a tendency to get out of date and is harder to fix to make it up to date.
  • “Looks cheap”-- i.e. when viewing docs by other teams already living this reality, they have a tendency to indicate that they are slightlly embarassed their docs are still on open api but that it's "just for now".
  • If not compiled by hand, the default generated openapi HTML thing has to be on a subdomain, which is worse for SEO and no CTA, same issue as Medium blog.
  • Less control over how to add annotations in docs.
  • Less visibility/ accessibility/ modifiability for people without Golang coding experience.
  • Fully integrating with swagger's format sufficiently to document everything involves more people on the team learning about the intricacies of swagger (instead of editing markdown that looks like any other markdown in the docs/website))
  • autogenerating docs is not the only way to make sure docs accurately reflect the API, even long term: the long term solution is to add accountability and process to how Fleet manages its API docs to ensure they are correct, regardless whether they are in a single markdown file that will probably never move, or spread across multiple Golang files throughout the code base.
  • concerns about generated docs go beyond presentation to maintenance, accessibility, and correctness
  • context: this is based on experience using swagger on multiple projects in the past and realizing that the generated docs became just as out of date as when they were handmade, except being generated makes them more difficult to edit and therefore gated/siloed.
  • The cause of out of date API docs: there needs to be more accountability about docs being correct, and stronger process to facilitate it, so they are correct every release
  • If they stay in markdown, they stay editable by anyone, and we avoid considerable extra work to get them compiling and presented in a way that's accessible. Everyone knows where to go to edit them: just click “edit” on the website.
  • replacing markdown files with code comments makes API reference docs harder to locate and edit, adds work to build tools to compile and attractively present them (especially with dev-friendly annotations), adds surface area to maintain all those tools, and limits who can edit them to people who are not intimidated by editing Golang files using OpenAPI syntax. (Vs the universe of people who can edit markdown; e.g. Tumblr users)
    • This could, in the future, be mitigated by expressing API docs in a programmatically parseable format in a single location (one file), outside of disparate code comments. But this would still require building and maintaining code to compile and present the docs, and would add considerable overhead. It would take a lot of value to make it worth the trade-off.

[mikermcneil]

@Desmi-Dizney expanded and softened some points, added clarification

[mikermcneil]

@Desmi-Dizney added checkboxes, additional bullet. I’m done editing now

[Desmi-Dizney]

@mikermcneil do you mind if I make some of these things more concise? I don't want to chop it up if you're committed. As it is right now, to me, it comes off as a wall of scary text. How would you feel about this linking to a keynote for the details?

[mikermcneil]

@Desmi-Dizney Agreed, thoughts:

• Lots to deduplicate here. I think many words can be cut by eliminating repetitive bits without losing any of the semantics or examples
• Would it be short enough if we reduce each checkbox to:
  • heading
  • plus a short paragraph of 1-3 sentences
• For any examples and points that don't fit, I think we can link to this issue repeatedly by lighting up relevant text like this

That work? If no good, we can grab a quick call to discuss, just Slack me

[Desmi-Dizney]

@mikermcneil This isn't quite what we had discussed but here is an example of one of the bigger sections being scaled back. Thoughts?

Why wireframe-first? Wireframing is called “drafting” at Fleet and is worked on in Figma. Anyone can make a wireframe suggestion, and wireframes are easy to contribute without being code literate. Drafting is completed for each change. It can be thrown away after changes. Coding first leaves verbiage that is difficult to update if it ever gets done at all. It allows you to simplify the creation and testing of error messages. Iterating in wireframes first lets us do all this for: Error messages Layouts Flows Interactions Help text Button text Forms URLs API parameters API response data…and more

[mikermcneil]

@zwass Couldn’t find the recording in a Google search, so I think no video exists, but I did find this Forbes article someone wrote about my talk at Apigee’s conference which might be helpful (it has a link to the slides from the talk): https://www.forbes.com/sites/danwoods/2015/10/19/dont-get-ubered-apis-hold-key-to-digital-transformation/?sh=78ea5302182c

[mikermcneil]

@Desmi-Dizney Thanks! Reads like a good start. Want to do the same for the others, then get a PR cooking to figure out structure?

Zach and I are working through some big picture decisions for how Fleet scales, so there will be edits and clarifications, but we can go ahead and get this into the handbook bit by bit as it’s ready, since it reflects where we are at today. Everything is in draft

[Desmi-Dizney]

https://github.com/fleetdm/fleet/issues/4821

Why do we wireframe first? Wireframes, or drafts are created in Figma to create wireframes. Anyone can make a wireframe suggestion, and wireframes are easy to contribute without being code literate. Drafting is done per change. wireframes can be thrown away after changes. Coding first leaves verbiage that is difficult to update, if it ever gets done at all. It allows you to simplify the creation and testing of error messages. Iterating in wireframes first lets us do all this for: Error messages Layouts Flows Interactions Help text Button text Forms URLs API parameters API response data…and more

Why mono repo?

One repo keeps all of the relevant work in one place. The only exception is when working on something confidential. One repo means that there is less to get lost. One repo pools GitHub stars to reflect Fleet’s actual presence better.

Why organize work in team-based kanban boards?

Kanban boards provide a uniform layout across all teams where anyone in the company can look to see what other teams are working on and have coming up. The different columns on the boards allow us to create a game plan for our to-do list for each 3-week iteration. These boards allow anyone in the world to contribute.

Why 3-week cadence?

Fleet product is released every 3 weeks, so everyone in the company is synced up to this same schedule. Other companies use a 4-week release cycle, but we like to move a little faster at Fleet to get more done. Everyone knows when the new release is, so they also know when their work is due.

Why agile?

See: https://agilemanifesto.org/ Collaborating and pushing for the next release creates the best product and culture.

Our values and mission.

See: https://fleetdm.com/handbook/company

Why the emphasis on training?

Investing in people makes them better and faster contributors. Creating a culture of helping others results in people feeling more comfortable and confident even if they aren’t familiar with osquery. A sharp focus on training means things are written down.

Why handbook-first strategy?

Watch: https://www.youtube.com/watch?v=aZrK8AQM8Ro For more details, see: https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/ Documenting in the handbook allows Fleet to scale up and retain knowledge for consistency.

Why not continuously generate REST API docs from javadoc-style code comments?

It looks cheap. Those using open API still are embarrassed by their docs. Generated documentation via tools like Swagger/OpenAPI has a tendency to get out of date and becomes harder to fix to make it up to date. There is less control over how to add annotations to the doc. It has less visibility/ accessibility/ modifiability for people without Golang coding experience. Fully integrating with swagger's format sufficiently to document everything involves more people on the team learning about the intricacies of swagger (instead of editing in markdown that looks like any other markdown in the docs/website)). Autogenerating docs is not the only way to make sure docs accurately reflect the API. Generated docs become just as out of date as handmade docs, except since they are generated makes them more difficult to edit and therefore gated/siloed. Adaptability is efficient. Using markdown allows anyone to edit our docs. Replacing markdown files with code comments makes API reference docs harder to locate and edit.

[Desmi-Dizney]

Added Why this way to the people section of the handbook. See: https://github.com/fleetdm/fleet/pull/4894

[Desmi-Dizney]

@eashaw How would I edit the onboarding to add the link for this?

[eashaw]

@Desmi-Dizney You can make a PR to the onboarding template https://github.com/fleetdm/confidential/blob/main/.github/ISSUE_TEMPLATE/onboarding.md

[Desmi-Dizney]

added link to https://github.com/fleetdm/confidential/pull/1086

[mikermcneil]

Closing the loop here with where this landed on the site: https://fleetdm.com/handbook/company/why-this-way#why-do-we-use-a-wireframe-first-approach