RFC: Discovery documents

[giorgiosironi]

Problem

Libero product features and architectural choices often go through a period of discovery where specifications can be produced and implementation options can be evaluated.

The process and its output can benefit from the standardization of discovery documents that enable collaboration by being shared between team members, across teams, and outside of eLife.

Suggestion

• Always track discovery work in at least one dedicated Github issue.
• Prefix Google Docs discovery documents titles with Discovery document:
• Move them into the single Libero shared drive.
• Link them from the relevant Github issue.
• Establish a timebox in calendar time at the start of the discovery activity.
• Organize in questions and answers; some of the answers are allowed to be assumption if clearly stated that they are.
• Link to a Github milestone if applicable.
• Add a TL;DR section at the top before closing the document at the end of the timebox.

Concerns

• A timebox helps limiting analysis time to favor prototyping and actual implementation.
• Replenishment meetings are a possibility for choosing the lenght of the timeboxes.
• Timeboxes are measured in calendar time so they need to take into account the percentage of time that is allocated to other tasks from the people that work on the discovery.
• Github milestones may not exist if the discovery is related to an aspect of the product or to architecture rather than to a particular feature.
• There is no explicit way to track the closure of a document on the document itself.

[diversemix]

The Reviewer team tend to do this sort of work on tickets. My worry is that if this work is done in this way there is no way of Product Managers tracking the work. Or is the fact ticket raise implicit?

/cc @hdrury1 @Maelplaine

[hdrury1]

Perhaps raise a ticket for the work, then link from there to the document (assuming it is easier to record in a document as diagrams etc. can easily be added/commented on inline). Once the work is completed, close the ticket. The ticket should also record the definition of done so we know when the document has reached that threshold. I'm assuming here (perhaps incorrectly) that the actual decision as a result of the information contained within the document would be outside the scope of the discovery itself. Alternatively, if no consensus decision can be made within the timebox then the tech lead for the project should call it?

[Melissa37]

And suggest cross link the googledoc with the Github ticket so if someone stumbles across it in google they can click on the Github ticket link and see if it's closed. Also, perhaps when ended, make googledoc read-only?

[giorgiosironi]

Perhaps raise a ticket for the work, then link from there to the document

As far as I know @Maelplaine is on board with the fact that work is always visible and tracked in tickets, and discovery work is no different. Adding to the description.

[giorgiosironi]

cross link the googledoc with the Github ticket

One suggestion was to link the tickets generated by the discovery, which is too much of an overhead with respect to linking to a milestone that is maintained on the Github side. Linking the discovery ticket should be very easy instead.

when ended, make googledoc read-only?

If there is a way to do this, I'll add it to the list.

[giorgiosironi]

when ended, make googledoc read-only?

If there is a way to do this, I'll add it to the list.

I can't find a way to do this as members of the Libero shared drive always have Edit access to everything. Also no lifecycle option on the document itself to change its state (like Github's repository archival option).

[Melissa37]

I assumed the owner to the doc always have the flexibility to change the setting on it, even if it belongs in a public folder. I think we do this on JATS4R

[giorgiosironi]

This is what I see when I try to reduce the permissions of https://docs.google.com/document/d/1XSnlohSju-XeZNfhlemAIrQPLflTOVAg5C1Nt6WGnug/edit which I own:

[Maelplaine]

@Melissa37 We can add a note at the top of the discovery google Doc to signify that the discovery is finished

[giorgiosironi]

Applying to https://docs.google.com/document/d/1QQdKcDwxo_dC8T4_ov4z6FA4YwQy7pKRZgrSpv1M2IE/edit#heading=h.tpcwpla9877m to see if it all works.

[giorgiosironi]

@joelsummerfield to give feedback as well, as he probably has his own format for documents.

[diversemix]

Something that has been discussed at the reviewer retro and again with @davidcmoulton and @thewilkybarkid ... is how does a decision get made and who makes it?

The document that we've been working on for front end alignment has a recommendation/suggestion in. Its not clear as to the process of to who the document is now distributed to make a decision.

/cc @BlueReZZ @gmaciocci @hdrury1 @Maelplaine

[giorgiosironi]

Not sure there is a standard answer, discovery is for opening up the options and discarding unviable alternatives. Eventually a decision can be made at various product levels (XML support and UI designs fall under different specialisms) or technical levels (general architecture, infrastructure, front end development all different specialisms as well).

[diversemix]

@giorgiosironi ... Ah I didn't explain myself very well. I should have used the word "approval" rather than "decision". So taking the example of the front-end discovery, reading through the document there is a well rounded technical reason for the recommendation. However, this needs to be approved by someone who has responsibility from the project, otherwise we could find ourselves heading in a direction that is then later questioned. Many document management systems have audit trails built in to accommodate this (not suggesting we use a document management system) - but we could put a table in all our documents that would reflect when significant changes were made and by whom and also when it was approved. This then gives the team reassurance that the work that they are doing and the direction they are heading has been reviewed and approve (much like code reviews).

[BlueReZZ]

Here's a proposal: there seems to be two broad categories of discovery document: one for exploring all avenues to limit scope for a particular feature or service, resulting in the definition of better acceptance criteria, and one for larger suite-wide and team decisions (like the front-end discovery).

Our goal in either case should be to record the decision and there are 3 mechanisms for doing that (well-structured GitHub tickets, the Decision Log and ADRs). For feature related decisions then the milestone or feature tickets contain the definition of what we decided to build, accompanied by acceptance criteria in the more technical tasks that relate to those features.

For suite-wide decisions, process changes or higher level stuff then we can record that in the decision log document as a first instance - this gives the reassurance we're after. At the moment that document needs some work as it is full of questions and answers that can now be turned into decisions (or were already turned into discovery). There are good examples of a decision logged in there with a link to the relevant discovery document. That document though isn't as accessible for the community so we should also record decisions as ADRs where appropriate which gives us a well-known structure for definition and also versioning. For example, after the discussions around areas of alignment I intend to create an ADR for each area.

In all cases, the approval should start with a conversation with the intention to log it somewhere for future reference and reassurance.

[giorgiosironi]

the decision log document as a first instance - this gives the reassurance we're after. [...] That document though isn't as accessible for the community so we should also record decisions as ADRs where appropriate which gives us a well-known structure for definition and also versioning. For example, after the discussions around areas of alignment I intend to create an ADR for each area.

I second the use of ADRs as they help discoverability by developers and by the community. This repository is the target for Libero suite-wide decisions. ADRs also have a model for being superceded and when stored in Git(hub) there is a clear audit trail of commitment and approval.

[diversemix]

What is the process of this getting approved or otherwise?

[giorgiosironi]

If people give a :+1: as a comment, I will turn this into a PR to add a corresponding ADR to this repository. Maybe we should use PRs directly rather than issues.

[BlueReZZ]

:+1:

[diversemix]

:+1:

[giorgiosironi]

In https://github.com/libero/community/pull/27