- From: r12a <ishida@w3.org>
- Date: Thu, 12 May 2022 11:33:31 +0100
- To: Internationalization Working Group <public-i18n-core@w3.org>
- Message-ID: <b79a6dab-5f0c-6b82-2bea-677c4a947116@w3.org>
I made the following changes to the way checklists work in specdev and merged them already so that you can play with it. One big problem we had was that the code dump produced a list of EVERY requirement in the whole document. The length of this was both too long for many specs to see the wood for the trees, and also required the WG to list the GH report in a wiki, separated from the report for the short review checklist. Furthermore, the checkboxes cannot be switched on and off in a wiki page (although the preset ones do appear, albeit greyed out). For many specs only a couple of sections are relevant and all the rest of the checklist is verbiage. So now each level 2 section produces a checklist just for that section. This means a little more copy-pasting, but on the other hand removes the need for mass deletion. In fact, only those requirements that the reviewer thinks are relevant to their spec are dumped into markdown, so in some cases whole subsubsections or individual requirements can be omitted from the final report. This makes it possible to produce chunks of markdown that will fit in a single comment field in a GH issue. In fact, it means that if you have produced a report for the short review checklist and added it to a GH issue, you can add the reports for the relevant specdev detailed checklists to that same issue page – thus keeping all the review information together in one place. You can see a mocked up example of the final output at https://github.com/w3c/i18n-discuss/issues/25. The new format also makes it easier to fill in the checklist. You no longer have to open each of the h3 section headings to see the whole checklist for a section. One click suffices. For each requirement there are 2 checkboxes. The first indicates whether the requirement is relevant for the spec: only requirements with this checkbox checked will be dumped to markdown. The second checkbox allows the reviewer to immediately indicate whether the spec fulfills that requirement. To save the reviewer's time, if you click on the 2nd checkbox the first is automatically selected, too (since it's obviously relevant). I did also consider whether it was valuable to have a checklist separate from the actual body of text (ie. could we expand/collapse the normal text, and add checkboxes to the normal advisment (orange) boxes. In the end i left it separate. This has a benefit of giving a better overview, and makes it easier to notice if you missing something. hth ri
Received on Thursday, 12 May 2022 10:33:35 UTC