agenda+ Changes to specdev checklists

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

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.


Received on Thursday, 12 May 2022 10:33:35 UTC