Add mock documentation #7
Conversation
There was a problem hiding this comment.
This looks like a practically useful and very usable flow for this kind of tracking in GitHub. My only concerns are due to GitHub's handling of issues themselves and the annoyance of issue templates changing or individual issue content deviating from the structure and so breaking the workflow. I am genuinly excited to see when the basics are ready and I can update some of the GItHub issue organisation on the SRR XNAT project to work with this.
Other thoughts I've had. In the templates, have you thought about using GitHub tasklists to cross link issues - e.g. in design inputs for user needs? That will give a nice list. I've seen this org and repo use GH Workflows to auto link issues and create tasklists: https://github.com/Australian-Imaging-Service/pipelines/tree/main/.github/workflows and Australian-Imaging-Service/pipelines#33
README.md
Outdated
| - Ensure that all QW items have versions | ||
| - Ensure the entire chain `design validation -> design verification -> design output -> design input -> user need` is consistent with QW rules, starting from the furthest stage of QW items. So if there is no `design validation`, then the chain will start from `design verification`. If there was only a `user need` and `design input`s, then only these would be validated | ||
| - Create word documents based on the QW template for export | ||
| - [name=Stef] Optionally? Create an html page that shows a burndown graph for each of the QW item types, showing the number completed and outstanding over time. Would this be useful? |
There was a problem hiding this comment.
I don't think that this is critical, but may be a nice to have for someone taking a quality lead role to see how well the system is being used
There was a problem hiding this comment.
Yes, management documents are planned. Not exactly sure what will be in them yet.
README.md
Outdated
| - Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) | ||
| - Would the burndown chart be useful to get an overview for development? |
There was a problem hiding this comment.
From my initial thoughts, the most useful bits would be to export and link tables to include in the software development plan, software requirement analysis, software detailed design, and software unit implementation and verification bits to comply with IEC 62304. The doc names may vary on the template you're using - those are based on Magda's interpretation of WEISS QMS I think and QNICE as an example. Other possibly useful templates at https://openregulatory.com/templates/
I think editing the templates will be needed as there will be other bits of content to update based on what the project is.
There was a problem hiding this comment.
Yes, templates should be copied in to the repo so that the devs can edit them as required.
|
|
||
| - Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) | ||
| - Would the burndown chart be useful to get an overview for development? | ||
| - Gate who can authorise a PR, or can anyone? |
There was a problem hiding this comment.
This will be project specific, and part of the process docs will define how releases are controlled. For example on SRR, we've stated that releases of software and docs need to be approved by Magda. So I think control of PR sign-off would be useful.
There was a problem hiding this comment.
Just considering this further, are we saying that every PR would need to be approved by madga in this project?
There was a problem hiding this comment.
And does this mean that you have the author, a normal approver plus Magda making 3 people?
| - Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) | ||
| - Would the burndown chart be useful to get an overview for development? | ||
| - Gate who can authorise a PR, or can anyone? | ||
| - Should we include a change request at this stage, or keep it with the risk management side of things |
There was a problem hiding this comment.
I'd say that a change request is to do with when the system is deployed and part of ongoing risk management so wouldn't be needed in a MVP. The interaction of risk management with design and testing would be very useful in a future iteration!
There was a problem hiding this comment.
I also noticed tha James has been tracking bugs and then the PRs that are closed, that weren't related to a specific user need, but not sure if that's required. Though does set up the case for ongoing surveillance post release
There was a problem hiding this comment.
Just to clarify, if a change was needed on an existing qw item, post freeze, would the change requester just modify the existing qw item from within github?
There was a problem hiding this comment.
yep they'd change it in github, and then on the next freeze command it'd prompt to say that it had changed and ask if its a negligable change (so keep it and dont increment the version) or the change requires a new version to be created
Co-authored-by: Haroon Chughtai <[email protected]>
Yeah agreed, if templates end up changing we'd have to offer a migration path for that or something else equally painful.
Chatted offline but yeah its a shame the beta of fully features tasklists isn't taking new users, so we can't develop for it. Using the basic tasklists at least gives the links so have updated to using that |
Co-authored-by: Haroon Chughtai <[email protected]>
README.md
Outdated
| If you have a different development flow than using the default branch, then edit the `qw` ruleset for the repository, adding extra branches to the ruleset (e.g. `develop`) | ||
|
|
||
| <!-- | ||
| - [name=Stef] or do we just define what workflow they have to use? Could also give a comma separated list of branch names in the --git-service option? |
There was a problem hiding this comment.
Excellent question! I would think that we would define the workflow and provide a document that explains it to the developers and the regulators. We can pull out their favourite branch names from the configuration file if that really helps. Whether changing the workflow is possible or sensible is a question for later. It might well be that the .qw directory is quite happy being split and merged and so it could be quite flexible.
|
|
||
| <!-- | ||
| - [name=Stef] For this I guess we should implement it in keyring using: service=`qw:github.com` username=`owner/repo`? | ||
| - [name=Stef] Should try and get a windows user early on to test that keyring works as expected |
There was a problem hiding this comment.
I could try it on Desktop@Home (or whatever it's called) if you like?
There was a problem hiding this comment.
yeah not a bad shout, not a masive rush but would be good to know early
| # Open questions | ||
|
|
||
| - Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) | ||
| - Would the burndown chart be useful to get an overview for development? |
There was a problem hiding this comment.
Yes! Managers love this stuff! Here is the rate we are burning down our risks, our Design Inputs and our Problem Reports!
We should absolutely store the state of the system at each qw freeze (or even more frequently) so that we can build these charts. May not be top priority of course.
|
|
||
| - Which document parts are the most useful for export, and would we want the user to be able to edit the template (update styles and placeholder text?) | ||
| - Would the burndown chart be useful to get an overview for development? | ||
| - Gate who can authorise a PR, or can anyone? |
There was a problem hiding this comment.
We absolutely need a list of people who are authorized and trained to do this. This list of people needs to be controlled by qw, so the open question is really more like "how do we control the list of authorized PR approvers, CR approvers and the like?"
There was a problem hiding this comment.
If we're gating PRs then it'd all be using github rules and codeowners files. Though I'm less sure QW should control this, and its more up to the users to make sure they comply with their own development process?
There was a problem hiding this comment.
This is an excellent idea. We should absolutely lean into github's natural way of doing things where they exist. Escpecially as gitlab does it too.
In this case our configuration should be split into many csv files (or similar) rather than one giant .json
Co-authored-by: Haroon Chughtai <[email protected]>
Co-authored-by: Stef Piatek <[email protected]>
Co-authored-by: Stef Piatek <[email protected]>
Seems to be what's being used in example documentation and is easier to understand from other contexts
…ockumentation # Conflicts: # README.md
|
|
||
| ### Creating a documentation release | ||
|
|
||
| When you're ready to update the documentation in your Quality Management System (QMS), you can use the QW tool's `release` command. |
There was a problem hiding this comment.
It seems to me that qw release should take templates and frozen items to produce one document per template. Must be frozen items, right?
|
Seems to me that we also need another subcommand, maybe called |
Figured actually better to get feedback using a PR, and then can tidy up the documentation afterwards