standard-for-public-code
standard-for-public-code copied to clipboard
standard-for-public-code
How do we stimulate documentation also for changing the organisational services
It is a big problem for public organizations. Higher level documentation are often missing. This can be a severe drag on uptake.
I'd like to report an issue in criteria/documenting.md.
In order to use or re-use certain software organisational and cultural changes are also often needed, without these, it can be hard to implement this software or even decide on using it.
The question is, what kind of documentation do business managers need in order to implement a codebase.
At the time of this writing, we see that https://standard.publiccode.net/criteria/documenting.html states that
"The documentation of the codebase SHOULD contain a high level description that is clearly understandable for a wide audience of stakeholders, like the general public and journalists"
and also
"The documentation of the codebase MAY contain examples that make users want to immediately start using the codebase."
In https://standard.publiccode.net/criteria/document-objectives.html we see similar language:
"The codebase SHOULD contain documentation of its objectives understandable by policy makers and management."
Given the question of "what kind of documentation do business managers need in order to implement a codebase", is the Standard missing requirements or guidance to managers/developers/policy-makers?
An example might be Signalen adoption requires municipalities to have processes established in order to really use the software, perhaps we can find examples where software makes processes obsolete -- perhaps these aspects should be highlighted.
Would this be in requirements or better expressed in guidance/further reading?
Given the question of "what kind of documentation do business managers need in order to implement a codebase", is the Standard missing requirements or guidance to managers/developers/policy-makers?
When we were doing #811 we also added some texts to the introduction of Bundle policy and source code. Specifically, I think of this sentence:
To be able to evaluate whether to implement a codebase in a new context, an organization needs to understand what process changes it must choose to make or how to contribute additional configurability to the existing solution in order to adapt it to the new context.
Does that cover the missing guidance?
We believe this is largely covered today. If not, we can re-open this issue with more specific details, or create new issues.