Create Google Docs version of the specification

[harisood]

Summary of issue

In order to make contribution as seamless as possible for a range of stakeholders with diverse skillsets, we are going to create a version of the specification that lives on Google Docs (GD), rather than just GitHub (GH). The process will be:

• GH specification is source of live truth
• GD specification synced with GH specification every Monday morning
• GD specification allows suggestions/comments by anyone
• By the end of Thursday, all GD suggestions translated to GH repo (process to be fully decided)

What needs to be done?

• [ ] Create Google Docs version of specification
• [ ] Decide process for translating to GH repo
• [ ] Document process for translation to GH repo

Who can help?

• @arron

Issue checklist

• [X] I have assigned the appropriate work package label to this issue, and added any other relevant labels
• [X] I have added this to the SATRE backlog (public) project board
• [X] I have assigned this issue to at least one person on the SATRE team

[harisood]

Things to consider:

• What happens is a comment isn't fully resolved on GD by the end of the week? Do we open issues on GH but maintain the comment on the GD specification?
• When do we decide something is resolved on GD specification
• Would a form be easier (reference part you want to comment on and your comment)

[manics]

I think the last option, a form which people can fill in, and reference which part of the doc they want to comment on (e.g. as a list of checkboxes, plus other), is easiest. However I'm happy to support something more complicated if people are willing to do the work to implement and run it.

[harisood]

@arronlacey and I agreed to give GD a go and sync it once a week, he's in the process of setting it up now!

[arronlacey]

I have created an MS Form mock-up for this https://dmail.sharepoint.com/:w:/r/sites/SATRE/_layouts/15/Doc.aspx?sourcedoc=%7BBDC4E02A-B599-471A-AE7F-1B1FD712239F%7D&file=SATRE%20Specification%20Edits%20Form.docx&action=default&mobileredirect=true

@manics what do you think? would you be able to draft up the final form?

[arronlacey]

^^ I can't think of a satisfactory way to do this with GD without a lot of continuous manual work to keep on top of it so I am backing MS Forms for this.

[manics]

@arronlacey yes, I'll update the demo MSForm that autocreates a GitHub issue when I'm back in the office, and share it for review/testing

[arronlacey]

Thanks Simon!

[manics]

@arronlacey How's this?

• https://forms.office.com/Pages/ResponsePage.aspx?id=OTEyrjoJKk2Bpl0zS82QGQQh5LWVyKJMjCf72dnH9PNUOUwzMlJWUFExQVBDRVBEOVlWRjY5UjVUSi4u
• https://github.com/sa-tre/satre-specification-private/issues/7

[arronlacey]

looks great @manics !

Let's inform everyone at the next Collab Cafe and maybe put a link into the specification itself?

[harisood]

Looks good! Can we explicitly mention email too in the last one, so we can e.g. get in touch with people to discuss further if we need clarification? Maybe even a different question?

I think we could also make it clearer that conversation will be happening on GitHub, so it would be absolutely great to get their GH username (or for them to create one using the walkthrough) so we can alert them to developments in the convo

[manics]

I think this form is the last resort- if there's a chance people are willing to use GitHub they should be encouraged to go that way and ideally should never even see this form in the first place. We could add email, but we need a way to keep track of it as information will end up in two places- the content of the issue which gets added to the public repo, and the private issue.

[harisood]

Agreed - though feel email would be good just in case a bit of clarification/key follow up question is needed

[manics]

I've updated the form and the GH issue integration, what do you think?

[manics]

I've also added some docs on the workflow to https://github.com/sa-tre/satre-specification-private

[harisood]

Sounds good! Is that workflow detailed enough?