Add anchors to each requirement to make deep links possible

[Ainali]

When we start making public compliance analyses of codebases, it would be really useful to be able to link to each of the requirements specifically rather than the entire criteria.

This has been discussed a number of times before and one big hurdle is that if we do assign an ID it becomes hard for us to switch order between requirements, adding new ones, or removing them.

This leaves us a few options:

1. refer to them with a hash (just in the anchor) rather than an ID that carries meaning. This comes with additional cost of handling them, which possibly could be mitigated by a content management system that can deal with this.
2. just use a serial number and accept that assigning an ID doesn't carry meaning, that they don't have to be in order, and it is okay to have gaps. This would also need a system to manage it, but could be as simple as a spreadsheet.
3. consider the standard to be stable enough that we can use ID's that carry meaning (like the second requirement of the third criterion, eg. 3.2) and bump the version to 1.0

Expanded from comment by @Ainali in https://github.com/publiccodenet/standard/issues/32#issuecomment-530327996

[Ainali]

An interesting way of doing 3. can be seen in this example for the Swedish law: https://lagen.nu/1960:729#P8S2 The anchor refers to paragraph 8, section 2. It works fairly well even over time, because when the law is updated, and the text of a paragraph is removed, it is still in there but the text now convey the removal, see the grey text both above and under this paragraph: https://lagen.nu/1960:729#P14S1 The paragraph above was moved to 42c and the below just removed. Notice how the law now don't have a §13 or §15, ie. incorporating some of the method of my point 2.

[felixfaassen]

This might be useful , A GitHub Pages compatible way of adding anchors to your headings without a plug-in or JavaScript :octocat:: https://github.com/allejo/jekyll-anchor-headings

Used the liquid template engine. We just add a simple html template which will create anchors to headings when rendered to HTML. This way we can just work as we do right now by not introducing any HTML markup inside our MD files but can link to the build/deployed standard online using anchors refering to any heading we want to have. If you find this interesting I can take a look at it how it works

[felixfaassen]

We do need to see how to implement this as the standard repo uses the remote jekyll-theme which is also used for our website and if it is desirable to put it in this theme. @bvhme @ericherman any takes on this?

[bvhme]

The headings in our themes already have their own id and can be directly linked to, the individual requirements don't though.

The problem here is that we can't generate them after the fact as the id for these needs to be version controlled as well as they are both parts of the content and are unique so should travel with requirements.

I'm wondering whether it might not make more sense to reconsider the entire content structure based on this principle. Perhaps the requirements should be first-class citizens and the criteria categories or something similar.

Personally I am quite afraid that anything we come up with here will severely hamper the ability to make editing easy, make contributing understandable for people less familiar with HTML/code and limit our ability to reorganize whilst we're not at 1.0 yet. All things that can be solved but that are not easy to.

I like this feature, but I feel the costs vastly outweigh the benefits.

[Ainali]

Personally I am quite afraid that anything we come up with here will severely hamper the ability to make editing easy, make contributing understandable for people less familiar with HTML/code and limit our ability to reorganize whilst we're not at 1.0 yet. All things that can be solved but that are not easy to.

This is a really important aspect, and a quite interesting tension. Yes, we do want it to be as easy as possible to participate and improve the standard and at the same time we are actually starting to apply the standard to codebases which increases the demand to referrability. What would a threshold look like for us to value ease of use over ease of improvement?

[bvhme]

Yes, that is the right question. To me, it would seem that we at least need to be able to make the statement that it is 'stable' as a 1.0.0. Until then, I hold that finding out what the requirements need to be and how they need to be worded is our mission. However, I think to some degree we should always make sure contributing is easy as it is part of use as well.

There are also other ways of looking at this problem. It could, for instance, consider breaking up criteria with more than 6 requirements reducing the need for direct links to criteria.

[ericherman]

I'm wondering whether it might not make more sense to reconsider the entire content structure based on this principle. Perhaps the requirements should be first-class citizens and the criteria categories or something similar.

I would support making the requirements the focus rather than only the grouping/themes of requirements.

Prototyping this will take dedicated work, yet has a good chance of yielding a superior result.

[bvhme]

I'm still pretty critical of this idea since I think it will make the Standard easier for us to use, but feel that missing the context-driven approach of the criteria will make it a lot harder to understand why to use it, and subsequently also how to use it.

I feel that the criteria sort of tell a story of why you should follow the standard. The requirements then stipulate what is necessary for that. Then, the guidence explains how. Finally the 'further reading' gives some context.

I'm a bit afraid that we run the risk of turning the Standard into a big-ass-list-of-requirements, like so many quality 'badges' out there and turn it into a soup of things that might be important.

[Ainali]

To me, who have been working with big-ass-list-of-requirements, it feels like the story should be broken out to an easy-to-read pamflet. Stories are great for inspiring people to adapt new ways of working. As a tool to do proper requirements management, stories are less useful.

[ericherman]

Yes, we invest in a prototype of a larger change, then we must also take a critical eye to whether it is drifting in the "soup of things" direction.

[bvhme]

Yes :)

I think above all we need to make sure that the 'learning curve' is smooth and does not have any big cliffs :)

[EdoPlantinga]

Related: I was looking into this, because for Demodam.org I would like to update the Demodam criteria. It would be handy if we could refer to the Standard, simply saying something like: for Demodam you MUST adhere to the Standard for Public Code V1.0.0 criteria 1, 4, 6 and 8, you SHOULD adhere to 2 and 5 and you MAY adhere to 10 (please note: just an example). Are the URI's meant to be persistent?

[raboof]

Related: I was looking into this, because for Demodam.org I would like to update the Demodam criteria. It would be handy if we could refer to the Standard, simply saying something like: for Demodam you MUST adhere to the Standard for Public Code V1.0.0 criteria 1, 4, 6 and 8, you SHOULD adhere to 2 and 5 and you MAY adhere to 10 (please not: just an example). Are the URI's meant to be persistent?

Perhaps this was discussed elsewhere and/or is a bit offtopic here, but I'm curious which parts of the standard you found you had to 'pick and choose' from: did you want to make the requirements "weaker" or "stronger"? Which ones? Do you think we should consider making some requirements stronger or more loose to make the standard more universally applicable?

[EdoPlantinga]

I meant it as a generic mechanism, but I think things like "All policy and source code that the codebase is based on MUST be documented, reusable and portable." are not likely to happen sometime soon. Same goes for "All functionality in the source code MUST have automated tests." Please note that the Demodam / Common Ground criteria that we are developing, may at some time also be used as criteria for formal requests for proposals (ie suppliers need to formally and legally confirm that they will adhere to these standards), which makes it all the more important to refer to (parts of the) standard in an unambiguous way.

[Ainali]

Are the URI's meant to be persistent?

In a way, that is something we aim for. But as in the v.0.2.0 release, we split one criterion into two. So while we kept the URI, half o the content ended up on a new one. So far, we have not made it possible to refer to a specific version of a criteria, and if we want to make it truly persistent, this would indeed be needed.

[ericherman]

The requirements under each criterion are still changing enough that it would be premature to create deep-links now. However, there's broad agreement within the staff that by release 1.0, these should be deep-link-able. Perhaps before, if we see the rate of change drop significantly.

[Ainali]

Just a note that this is in the roadmap.

[ericherman]

The problem here is that we can't generate them after the fact as the id for these needs to be version controlled as well as they are both parts of the content and are unique so should travel with requirements.

@Ainali and I agree that we need a way to specify the anchors so that they can remain even if we reorder the requirements.

It is adding clutter to the markdown, but we could create anchors for each, perhaps a bit like:

## Requirements                                                                 

* <a id="r1">The codebase MUST allow anyone to submit suggestions for changes to the codebase.</a>
* <a id="r2">The codebase MUST include contribution guidelines explaining what kinds of contributions are welcome and how contributors can get involved, for example in a `CONTRIBUTING` file.</a>
* <a id="r3">The codebase MUST document the governance of the codebase, contributions and its community, for example in a `GOVERNANCE` file.</a>
* <a id="r4">The contribution guidelines SHOULD document who is expected to cover the costs of reviewing contributions.</a>
* <a id="r5">The codebase SHOULD advertise the committed engagement of involved organizations in the development and maintenance.</a>
* <a id="r6">The codebase SHOULD have a publicly available roadmap.</a>         
* <a id="r7">The codebase SHOULD publish codebase activity statistics.</a>      
* <a id="r8">Including a code of conduct for contributors in the codebase is OPTIONAL.</a>

A quick test showed this to work as expected, but has the obvious downsides of making the contents less easy to read in the markdown version.