Python guide: Update landing page of the guide

[gkunz]

The landing page of the guide should be updated to make it more consumable for readers. Improvements include:

• describe the purpose of the guide
• describe how to read the guide
• describe how to contribute to the guide
• correct broken links
• check how to make the size of the tables more consistent

[myteron]

Hi @gkunz , the current main page has been put together rather quickly. Thoughts, not intended as content:

Main purpose:

In some organizations designers must study this type of content. Its designed as a read-through/self study where you do not suffer studying it.

Issues we have seen in secure coding guides that we like improve on:

• Java guide clocks at 40hours, that is without breaks.
• Rules with questionable existence, without a real-world CVE.
• Content written for word count (fluffy).
• Only skeleton code, can't run it, no fun or proof that the example is valid.
• Missing modern technical documentation writing style.
• Multiple code examples explaining the same thing.
• Non-matching code examples, titles and/or docs.
• Overall dead, to hard to contribute to due to its license + non-public storage.
• Hard to post-process code examples (scraping required)
• Rating and Prioritization is outdated of flawed.
• Hard to know what rules relate to availability/stability or other security issues.

How to read:

Good learning material allows a to study in a continues line. The CWE structure we use does not allow that as one can see in: https://github.com/ossf/wg-best-practices-os-developers/blob/main/docs/Secure-Coding-Guide-for-Python/Intro_to_multiprocessing_and_multithreading/readme.md missing on the main page. Not sure what do to about this atm.

I believe It is important to allow a designer to study the content in their natural habitat meaning programming IDE with a cloned git. Not on some web-server regardless of confluence or what not.

How to contribute to the guide

Overall I like to avoid overloading the main page. Main content of this shall not live on the main page. It shall only be mentioned when it helps with the study of the content. I avoid having it in the repo as such.

What we need is:

• Mission statement; why and for who we do the python secure coding guide.
• Page template/style guide
• Folder structure guide. (this might end up in "how to read this".)
• Naming conventions of files noncompliant01 compliant01 example01 image01 and folders CWE-XXX
• Who and how to get in contact. I am actually not sure how this is going to work the /// email.

Some of this type of content exists partially on our internal confluence page.

Correct broken links

Needs automation

Make the size of the tables more consistent The current hard-coded generation of the main page may change. Eventually we like to automate some of the evaluations such as the risk rating and coverage of static parsers on the main page.

We had a hack for it <img width=680> in the last empty row that was removed in order to make the linter happy. I honestly don't care what the linter has to say if basic functionality is missing.

[gkunz]

Hi @myteron, all very good input. It seems, we may want to address some of these points individually. I'd rather leave writing about the purpose to you as the driver, but I'll take on other, smaller things such as linking to a contributor guide (externally of the main landing page), the tables (the linter config can alwasy be updated - it should serve us, not the other way around).