Add more information about issue preparation

[marcoow]

Adding sequences of steps to be takes in order to complete an issue is IMO one of the central points about good issue preparation. The playbook was lacking clear guidance around that so far though which this PR now adds.

[marcoow]

I think we ultimately agree, but we need to make it very clear that "preparing an issue" is more than "just think through the steps in 10 min" and is more like "implement it until it works reasonably realistically and then describe what you did".

That's precisely not what I think it means :) The point is preparing the sequence before starting the implementation. You cannot escape the need of other stakeholders to have some kind of notion for how long something will take etc. The only way to understand that in my experience is to think about what precisely something means aka what the steps are.

I don't think it's only possible to come up with these steps for trivial issues and I'd also recommend being careful to confuse this with Qonto's dive-ins which deal with tasks at a much larger scale as far as I understand it. I think the scale of those is in fact so big you'd not be able to capture everything in the level of detail I'm describing here without a prototype. If you look at a task that will take one person 1-2 days though that's well possible – I've been doing this for years and taught others how to do it as well.

The point is that when you figure out what the steps are while implementing them at the same time (or in reality you're figuring out what the next step is, implement that, figure out the next step after that, implement that, etc.) that has some negative implications:

• you won't be able to give anyone an indication of how long the task might take since you don't actually know what the task is
• uncovering hidden complexities or missing dependencies (e.g. missing designs etc.) only after you started implementation has higher cost since you'll have to go back to a previous step and change that, pause your work on a task because you need to get designs (that you didn't realize you needed when you started implementation) or other dependencies etc.

I have a lot of sympathy for the notion of finding out what the work is being a central part of doing the work. That's what I tell clients when we talk about multi-week or month projects: neither do we know nor do they know what exactly the scope of the project is and finding out what it is in fact is a big part of the project. I do not think that's true for all scope sizes – a much smaller scope (that of an issue) is much easier to capture and think through. You'll still miss some things but that doesn't mean the effort doesn't also save you a bunch of problems (see above).

From a talk I gave on the topic – bigger scope cannot be prepared in detail (that would be the old waterfall-model 500 page spec document which will be wrong anyway) but small scope can be:

In general whenever you think you're not able to compile that sequence of steps for an issue, that's a good indication you might need a research/prototype spike first (we're saying that elsewhere in the playbook) but in my experience over the past few years that's the exception.

[Turbo87]

but in my experience over the past few years that's the exception.

yeah, maybe. for Qonto it's the unfortunate reality :-/

[BobrImperator]

In my opinion the way to plan out your work that is described here works although like with everything it depends.

In my experience, it depends on a subject, if it's something like adding some simple API or some component, it's likely that what needs to be done is known at a glance, with that I can sit down and plan out the work and figure out if there's something I'd need from other team members. Doing relatively small things that are easy to figure out in advance is really good, because the issue itself can become somewhat of a documentation, contain reproduction steps as well which ultimately would also result in testing scenarios.

But sometimes it's just like Tobias says, even if the output of some module is known, the implementation might not be as straightforward and might be difficult to plan out in advance, in that case working alongside prototype implementation will be more productive because that way I can get some things going while figuring out the next steps, even though it might require some backtracking. In my case a lot of times just doing something and brute forcing my way through is much more productive than trying to plan out things before.

[marcoow]

I completely agree that sometimes spikes and prototypes are needed and as I said, we explicitly recommend relying on them in the playbook as well. I'd say though that if you're consistently not able to prepare tasks thoroughly that usually means they are too large (e.g. weeks of work instead of ca. 2 days) or you're working on a more research/debugging-oriented topic for which any kind of iteration/sprint origanization might not be too helpful at all…

[marcoow]

Here's an example for the level of detail I have in mind btw:

• add a React context for sharing the profile data loaded on the profile verification route (see [link])
• populate the service on the profile verification route (see [link])
• add a React context for sharing the collections loaded on the profile verifications route (see [link]): countries, career levels, functions, industries, salary ranges
• populate the service on the profile verification route (see [link])
• add an outlet on the profile verification route and a new subroute /profile/:id/verify/personalDetails that routes to src/routes/profile/verifiy/personal-details.js
  • on that new route, render the <EditPersonalDetails> component (see [link])
  • pass the profile information as received from the context for sharing the profile data added before
  • pass the list of countries as received from the context for sharing the collections added before
  • add a back arrow to the /profile/:id/verify/personalDetails route that navigates to the /profile/:id/verify/ route
  • add a save button that when clicked, saves the current personal information (as received via the <EditPersonalDetails> component's onChange callback) to the API (see API docs below)
  • if the request succeeds, update the profile in the context for sharing the profile data and navigate to the /profile/:id/verify/ route (this requires a new msw mock to be added)

This covers all steps of adding a new route in an app using an existing component and making it functional. Thinking it through and writing it down like this helps uncover hidden complexities (e.g. I only realized we needed those contexts mentioned in the first points while doing this) and serves as guidance for potentially less experiences team members that might work on the task.

[BobrImperator]

@marcoow Could you add that as an example to the README?

[marcoow]

Yeah, I'll polish it a bit and update the example 👍

[marcoow]

@BobrImperator we have an example issue in this repo – what do you think about that?

[BobrImperator]

I think that's good, I forgot about it though, found it once when after I was hired but not sure how. Do we have a link to it somewhere? Or should it be added here?

[marcoow]

yeah, I'd add that in the text as well then

[marcoow]

I improved the example a bit and updated the TODO list in the text