Find examples for elements of the standard

[ericherman]

What should a README contain?
What should a CONTRIBUTING file contain?
What should a GOVERNANCE file contain?
What should a ChangeLog file contain?

Find two examples for each file showing "minimum to meet the bar" and "best of class" real-world examples.

[ericherman]

@ElenaFdR requested that we be on the lookout for good examples of architecture descriptions/diagrams, especially from public projects.

Having multiple examples means we could show a range from "best of class" to "minimal, but good enough".

[Ainali]

There might be some useable examples in this category: https://commons.wikimedia.org/wiki/Category:Software_architecture

[ElenaFdR]

Expand with:

• examples of governance docs for thriving communities

[bvhme]

I made for Amsterdam, as a reference:

• Guide on writing a README
• Contributing

[Ainali]

I was thinking a bit on where to add these and perhaps we could start by creating a resource from the related actions in in the new page product-assets-for-early-incubation.md that explains them a bit better and have these as linked examples. If needed they can later also have guides for more detailed how-to's when we have more material and developed thoughts for them.

[clausmullie]

This issue starts from the standard for public code, and then tries to identify if linked resources as recommended reading or separate assets can be useful. Should this issue then be in the standard repo?

[Ainali]

Should this issue then be in the standard repo?

It's a good question, and I guess it depends on how extensive this collection should be. The Standard should probably be a quite "clean" repository that only includes the actual standard itself (and basic metadata and documentation for the repository). So if it's just a one-liner in Further reading yes. But more extensive "add-on" guides should live somewhere else. Perhaps on about, or if it is really comprehensive, in a repository of its own.
And when that has been created, it should probably be linked from the Standard as further reading.

[ElenaFdR]

Should this issue then be in the standard repo?

Nope. I saw this as being explicitly a stewardship resource - so that stewards helping a community meet the Standard have a database of useful examples to share with codebase communities.

There's a big difference in the amount of completeness/justification required for your own resource for your work vs a resource deliberately provided to the whole community.

[clausmullie]

Perhaps my question is this:

1. Having the standard as a "clean" repository made sense previously, as it was an asset we develop and maintain. So it's the core ingredients, with the 'messy implementation stuff' on our About repo.

2. However, in light of our recent community call in which we discuss making the standard more replicable within the community, the discussion includes having localised flavours, localised implementations, example repositories and so on.

3. Where then, should this activity take place? If the standard repo remains 'clean' - and we host our own 'implementation tools' on About, should community members then also keep their assets in their own spaces/places? Or we do create a space for community members to also contribute their implementations (ie 'the OS2 kickstarted guide to a new repo') and other 'messy assets' (ie 'how to check against the standard as a vendor') to the standard repository for other community members to find? In case of the former, me might want to start a list of community implementations?

Question is not a priority, but just parking it here for now.

[Ainali]

3. Where then, should this activity take place?

My first thought is that a "flavor" or "localized implementation" would be a downstream repository, nothing that affects this repository at all. This has the advantage that anyone can set it up at anytime and without their adaptations affecting any other user of the standard.

[Ainali]

I think that everything discussed in this issue should be integrated in the implementation guide we are creating, see publiccodenet/projects#112.

[ericherman]

As we're working with https://github.com/diggsweden/open-source-project-template and https://github.com/OS2offdig/OS2produkt/ to help refine good templates for essential files in the https://github.com/public-code-templates/public-code-repository-template repository, I think this issue should change focus: there is still utility in linking some good examples, in particular two examples for each showing "minimum to meet the bar" and "best of class" real-world examples. Perhaps a title change is in order?

[Ainali]

Would we want "minimum to meet the bar" to be a file that only meets MUST requirements (and has good reasons to not meet the SHOULDs) or would it be a file that meets both MUST and SHOULD requirements and doesn't have the need for explanations/exceptions?

[ericherman]

To me, a codebase having good circumstantial reasons for SHOULD exceptions is a different axis than understanding completeness between minimum-to-meet and best-of-class.

Thus, I think ideally it would be all MUST and all SHOULD, to avoid confusing those two dimensions.

However, if there happen to be SHOULD requirements which are explained as exceptions, I think that could be fine.

But, let's see what we find.

[Ainali]

I agree. And then logically, a "best of class" then meets all OPTIONAL as well, right?

[ericherman]

Given that most OPTIONAL are things that we would recommend, then I'd say likely, yes.