Website Content Review

[eddie-knight]

Link to website: https://tag-security.cncf.io/

In order to increase the quality of outputs from TAG Security, to simplify the project maintenance, and to streamline new member familiarization, there is a need to do a large-scale cleanup of this repository. This will involve the revision or removal of files and/or directories.

As a first phase, we will be scoping focus specifically to content that is displayed on the website:

# snippet from website/Makefile
--include='assessments' --include='assessments/**' \
--include='governance' --include='governance/**' \
--include='supply-chain-security' --include='supply-chain-security/**' \
--include='*.md' --exclude='*'

This issue description will be used to summarize unique work items that we have found, which should be tackled. Unless otherwise noted, PRs and comments are welcome from anyone in the community to address the questions or problems outlined below.

Action Items

### Assessments
- [x] README: Minor typos
- [x] README: Simplify language / reduce length
- [x] README: Does "Components of the TSSA package" imply that a STAG review required by the TOC must involve a self- and joint- assessment? (It shouldn't reference the TOC at all)
- [x] guide/self-assessment: Ensure all language surrounding intent or usage matches the current strategy for reviews and assessments

### Events
- [x] README: Add new heading for "Recurring Events"
- [x] Move events into primary repo structure (outside of website/content/)

### Governance
- [x] Consistent capitalization of page titles (this applies to every section, really)
- [ ] roles: Should we consolidate all of the different roles files into the core roles.md?
- [x] charter: TODO: Review this with current TAG leadership. (Is the Charter up to date? Have we been properly acting in accordance with the charter goals and commitments? Are we using it to effectively equip and onboard leaders?)
- [ ] comunications: Is this used? Should it be used more? (no, no) (#1301)
- [x] presentations: Is this up to date? (yes)
- [ ] process: Is this up to date? (yes, but it's duplicative with CONTRIBUTORS.md)
- [x] related-groups: This seems incomplete (#1261)
- [ ] tools: This seems like a stub, and it seems like it might not be governance related (#1301)
- [x] Full Directory: Move anything that pertains to contribution governance (members, groups, etc) to a new directory. Remove Governance from the website.
- [ ] CNCF-projects: replace this with a [link to the landscape](https://landscape.cncf.io/?group=projects-and-products&view-mode=grid&tag=security) (#1300)

### Supply Chain Security
- [x] **/images: we should create a naming convention for image directories, and omit them all from showing up in the sidebar
- [x] Is the secure software factory a whitepaper? Should we have a top-level directory for whitepapers instead, and include all of them there? TODO: Co-chairs meet to decide approach.

### Blog
- [x] Do we want to keep the blog? (yes)
- [x] Do we want to keep the old blogs?
- [x] Do we want to add new blogs?
- [ ] TODO: document the intent, standards, and process for contributing (governance or contributing dir?)
- [x] TODO: add structure for organizing by year

### Publications
- [ ] The publications table is too wide— in the final column "Link" four letters is getting broken up into two lines.

[PushkarJ]

Thank you for creating this space to track all this upcoming work.

While we are working on this, let's see if we can add a banner "website under construction" 🚧 on website pages and link this issue in the banner for any feedback folks may have :)

[mrcdb]

Great initiative @eddie-knight !

With regards to the point related to the TSSA package, I think clarification may be needed in the self-assessment guide which currently states that:

This document provides the CNCF TAG-Security with an initial understanding of [project] to assist in a joint-assessment, necessary for projects under incubation. Taken together, this document and the joint-assessment serve as a cornerstone for if and when [project] seeks graduation and is preparing for a security audit.

[eddie-knight]

Thanks @mrcdb — I'll keep the list updated with any comments that roll in here.

[eddie-knight]

Notes from one point of discussion on today's NA TAG meeting.

Problem

Recent discussion has raised concern as to whether thegovernance/ directory has a reasonable amount of clarity with regard to the intent of its contents. Similarly, it has been suggested that there are too many top-level files that relate to project governance. (for example, multiple files related to the project license).

Proposed Solution

Reorganize, merge, or remove any content related to governance and contribution. The result should be fewer and clearer files and directories in this repo.

[eddie-knight]

Notes from recent discussions regarding the presentation and accessibility of STAG whitepapers. Needs input from at least @mnm678 & @PushkarJ.

Problem

Whitepapers are currently spread across multiple locations in this directory, organized by topic. In some cases, they live nested alongside other topically related content.

Proposed Solutions

Multiple possible options exist, which I'll list here sorted by complexity of effort.

Option 1: Highlight PUBLICATIONS.md

An attempt to resolve this problem has been made in the past, through PUBLICATIONS.md at the top level of this directory.

Unfortunately, this has not been immediately clear to many new members— possibly due to the relatively high number of files and directories at the top level of the repo.

This is the best temporary solution, and maybe it's a permanent one: I'll map PUBLICATIONS.md to a navbar position on the website, and remove any reference to other whitepapers (ie, Supply Chain Security) from the navbar.

https://github.com/cncf/tag-security/pull/1265

Option 2: Bring whitepapers together into a single directory.

Note: This will break any backlinks to the whitepapers.

2a: top-level directory.

Instead of topical organization, we could have a top-level directory called whitepapers/. We would move all whitepaper subdirectories into this new directory, as well as the audio-versions/ top-level directory. This will allow us to create a simplified presentation

2b: consolidate topical directories

If we consolidate top-level directories based on topics and working groups, we can create a standardized flow for how each WG stores its artifacts. This will have the added benefit of allowing quick population of all WG content (and whitepapers) onto the website (though the whitepapers will be nested enough that I suspect they won't be intuitive to find)

Option 3: Simplify the website, but not the repo

If we want to leave things how they are in the repo, we could just write up some additional custom logic in website/Makefile to move each whitepaper from its current disparate location to a centralized location that will only be reflected on the repo.

Note that this will break the current pattern of the website layout reflecting the repo structure.

[amanda-gonzalez]

hi @eddie-knight I saw this issue marked as a good first issue, I've done a security self-assessment as a security pal this past year and I would love to help edit the assessments page if needed (or any of the other tasks)!

[eddie-knight]

Hey @amanda-gonzalez thanks for raising your hand! Would you like to create a PR with any improvements you find?

We're hoping to have most of the changes merged this week, so please ping me here or on Slack if I can help clarify anything.

[mrcdb]

hi @eddie-knight I am looking at the Events page in the website and it looks like this is statically built from the website folder and not built from Markdown files originating in the rest of the repo.

To make this more consistent with other sections (Assessments, Governance etc), would it be beneficial to create an events top level folder in the repo with a README detailing recurring and future events, as well as an archive of past events (on this, we have a past-events.md file in the root which may be moved to the new folder IMO so it gets automatically published on the website as well).

[eddie-knight]

Yeah, I think the best route would be to move events into the community directory that was recently created— the plan is to start moving more content in there from around the repo. Would love to see a PR for it, if you have the time.

[brandtkeller]

With merge of #1279 how many of the assessment objectives remain?

[eddie-knight]

I think the assessments content is in a good state for the current sprint. I have some questions and nits that I want to address over time, but I think Amanda's contribution is plenty sufficient for the goal of removing the "under construction" banner.

[mrcdb]

@eddie-knight are the action items on the Events section complete or do you foresee additional work required to fix those issues?

[eddie-knight]

Thanks @mrcdb - I think there is more to do there. I tried automating it to act like the blog, but didn't get anything behaving how I imagined after all.

[brandtkeller]

As a follow-on item, we should discuss what to name/do with process.md