Closed anvega closed 1 week ago
Name | Link |
---|---|
Latest commit | 1f7b9ec46fc2bd7b220ce401fbc93fc74749d933 |
Latest deploy log | https://app.netlify.com/sites/tag-security/deploys/666c728b9970cc000838a480 |
Deploy Preview | https://deploy-preview-1270--tag-security.netlify.app |
Preview on mobile | Toggle QR Code...Use your smartphone camera to open QR code link. |
To edit notification comments on pull requests, go to your Netlify site configuration.
This is a great outline for guidance and enabling the TAG to continue to iterate.
I imagine there are a great many points that could be added - and I don't want to keep this from merge otherwise - but I do see one partially covered topic that I believe lies somewhere in the lifecycle of publications.
Do we want to include any guidance for efforts we target as high-value and as such want to keep publishing versioned updates? Do we have an obligation to do so with the items we publish or is there an expectation of best effort or otherwise deprecating after some period of time without intent to update?
Willing to take this as a topic outside of this PR.
I agree with @brandtkeller that publication maintenance should at least be mentioned here. We can elaborate on it later if needed.
On another note, we should also incorporate (merge or reference) existing guidance, such as:
When people are energized about writing, they often aspire to maintain their work long term, thinking of it as a living document. However, static versioned documents are harder to maintain than software projects. In practice, nothing gets updated until something bad enough is spotted or there’s a clear incentive for how dated something becomes. Also people’s priorities shift over time, impacting their ability to keep past work current.
For the dozen publications we have made, only the Security White Paper has seen updated versions or later editions. A few of the Supply Chain publications have had small fixes. We can mention the aspiration for ongoing updates in our guidelines but also acknowledge the reality: maintenance typically happens when there’s a compelling reason. We should encourage regular reviews and collaborative efforts while recognizing that some documents will inevitably become outdated without a strong incentive for revision.
Most importantly, I want authors to focus on writing something that meets these guidelines at the time of writing and only worry about future maintenance once they are done. Any post-completion or future maintenance plans should be included in the other two documents that focus more on the larger process/lifecycle beyond just authoring.
I consolidated the three publication guidelines under a single folder and added cross-references between each. I also renamed the new doc on publishing guidelines to authoring guidelines for clarity.
Liking the direction and overall flow
I know the compliance WG has a number of white paper ideas currently, so CC @rficcaglia , Anca, etc. for thoughts/feedback
Thanks for the approval @PushkarJ!
This PR introduces a new document, guidelines.md, which outlines the publishing guidelines and standards for the CNCF Technical Advisory Group. The purpose of these guidelines is to ensure the production of high-quality, consistent, and impactful publications. Key points include content quality, structure and organization, writing style, technical accuracy, technical rigor, references and citations, review and revision, and formatting and presentation. These guidelines will help authors produce valuable resources for the community while maintaining a low-friction, enjoyable publishing process.
The guidelines emphasize the importance of considering these standards upfront to ease the burden on volunteers who handle proofing and editorial work.