-
Notifications
You must be signed in to change notification settings - Fork 4.3k
Add comprehensive cheat sheet creation guide (GUIDELINE.md) #1768
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
…e documentation references
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Excellent!
|
There are several lint errors, for example: GUIDELINE.md:1 MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "# Cheat Sheet Creation Guide"] |
|
Will fix the errors this weekend 👍 |
|
A few more still exist : GUIDELINE.md:124 MD036/no-emphasis-as-heading Emphasis used instead of a heading [Context: "1. Background & Context"] |
|
One markdown bug left! GUIDELINE.md:295 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```java"] |
GUIDELINE.md
Outdated
| - Functionality: Code examples work as intended | ||
| - Security: Examples implement security best practices | ||
| - Compatibility: Examples work across different environments | ||
| - Performance: Examples don't introduce performance issues |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO remove this
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just the performance part of Testing criteria section?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO only Performance
GUIDELINE.md
Outdated
| 1. Unit Testing: Test individual code examples | ||
| 2. Integration Testing: Test examples in context | ||
| 3. Security Testing: Verify security properties | ||
| 4. Performance Testing: Check for performance impact |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO remove this
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just the performance part of Testing process section?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes the performance section does not apply to this project
GUIDELINE.md
Outdated
| --- | ||
| ## Maintenance & Updates |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This does not match what we or contributors do
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just wanted to confirm, you want me to remove entire section and directly go to section 7.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@mackowski bump on the comments and new commit review
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, the whole section should be removed
|
I agree with all of Mac’s change suggestions.
|
|
Just noticed the linters fix led to a bit messed up previous section 7, now section 6. I need to fix section 6 and check if I get new linter related issues. |
|
@mackowski has the lead here, let's patiently wait for his review :) |
GUIDELINE.md
Outdated
| - Functionality: Code examples work as intended | ||
| - Security: Examples implement security best practices | ||
| - Compatibility: Examples work across different environments | ||
| - Performance: Examples don't introduce performance issues |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO only Performance
GUIDELINE.md
Outdated
| ``` | ||
| ### 6.2 Advanced Template Features |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
was this all tested? Is it working in markdown and on the website?
GUIDELINE.md
Outdated
| ## Additional Resources | ||
| ### Further Reading |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This further reading is not helpful in this context right?
GUIDELINE.md
Outdated
| - [GitHub Markdown](https://docs.github.com/en/github/writing-on-github) | ||
| - [MkDocs Documentation](https://www.mkdocs.org/) | ||
| ### Community |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is the benefit of having this here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
let me remove the whole additional resources section.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unless, we want to embed a section dedicated for adding owasp channels or route users to contributors and chat with them.
|
I left some comments + Markdown linter is failing + I would like to see an example of at least one cheatsheet created (by human or LLM + human) based on this guide to see what is essential in this guide and what is not needed. |
You may look at what MCP Cheatsheet team is doing here https://docs.google.com/document/d/16LvkpUOC5arYl1uIjBglIg9UhoOKm1Lsb6OJYUJhfPU/edit?tab=t.1hsjuwcid34z#heading=h.i6wuwte0l3gd Do you want to recommend any other new cheatsheet who can leverage what we have suggested in this PR? |
GUIDELINE.md
Outdated
|
|
||
| Recommended Content Length: | ||
|
|
||
| - Comprehensive Coverage: 3,000-5,000 lines of content |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We do not want so long cheatsheets
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
agreed, let me remove it.
GUIDELINE.md
Outdated
| Recommended Content Length: | ||
|
|
||
| - Comprehensive Coverage: 3,000-5,000 lines of content | ||
| - Practical Examples: 20-30 code samples per cheat sheet |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From where you get this number?
GUIDELINE.md
Outdated
|
|
||
| - Comprehensive Coverage: 3,000-5,000 lines of content | ||
| - Practical Examples: 20-30 code samples per cheat sheet | ||
| - Multiple Perspectives: 3-5 different approaches/methodologies |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you give an example of 3-5 cheatsheets that are doing that
GUIDELINE.md
Outdated
| - Comprehensive Coverage: 3,000-5,000 lines of content | ||
| - Practical Examples: 20-30 code samples per cheat sheet | ||
| - Multiple Perspectives: 3-5 different approaches/methodologies | ||
| - Cross-References: 10-15 links to related topics |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is too much
|
I think the general gist of this cheat sheet is just too much. Cheat sheets aren't comprehensive guides, and we certainly don't want an extremely long document explaining how to write them. |
I agree, how about we just keep Section 6 template? Let's keep it simple to start with. Just keep this section 6.1 Basic Cheat Sheet TemplateI think this is the core and the most useful part. I can delete rest. Thoughts @mackowski @szh @jmanico? |
|
I love that idea |
…- Remove excessive content and keep it simple
CONTRIBUTING.md
Outdated
|
|
||
| ### Structure | ||
|
|
||
| > **Need help with content structure?** Check out our comprehensive [How To Make A Cheatsheet guide](GUIDELINE.md) for detailed structure guidelines, content organization, and best practices. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe this should say something like "Check out our template" or just "Check out our guidelines" now that it's not comprehensive.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still needs to be addressed
GUIDELINE.md
Outdated
| @@ -0,0 +1,260 @@ | |||
| # Cheat Sheet Creation Guide | |||
|
|
|||
| ## How to Create Comprehensive Security Cheat Sheets | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd remove "Comprehensive". That's not what we want in a cheat sheet.
GUIDELINE.md
Outdated
| ## Executive Summary | ||
|
|
||
| This guide provides a comprehensive framework for creating high-quality security cheat sheets based on analysis of 100+ OWASP cheat sheets. It covers structure, content, formatting, and best practices for creating authoritative security guidance documents. | ||
|
|
||
| **Target Audience**: Security professionals, developers, technical writers, and anyone creating security documentation. | ||
|
|
||
| **Based On**: Analysis of 100+ OWASP cheat sheets ranging from 44KB to 212KB in size. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For brevity I'd honestly remove this whole section
GUIDELINE.md
Outdated
|
|
||
| ## Conclusion | ||
|
|
||
| Creating comprehensive security cheat sheets requires careful planning, thorough research, and ongoing maintenance. By following this guide, you can create authoritative, practical, and valuable security guidance that helps practitioners implement effective security controls. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This sounds too mellow and AI generated. I don't think it's necessarily bad, just very non-human.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ack, let me make changes to this language.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Still needs to be addressed
GUIDELINE.md
Outdated
| --- | ||
|
|
||
|
|
||
| *This guide is based on analysis of 100+ OWASP cheat sheets and represents best practices for creating comprehensive security documentation.* |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you share more details on how this analysis was performed and how it was used to generate these recommendations?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sure, I downloaded all the cheatsheets and ran an analysis on it using Cursor. Looked for common patterns and gaps and provided template based on this analysis. Comment for reference #1745 (comment)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would love more details on what the analysis was. Like what prompts were used, etc. if you still have.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @szh, I had created this document when I worked on analysis of Threat Modeling Analysis for 100+ threat models https://docs.google.com/document/d/1RkpBgLICnTbpPQLeIxc7njzQC3ULhAHH/edit
Unfortunately, I didn't document something similar for this guideline analysis. Let me know if this gives you a good idea of how the analysis was performed.
GUIDELINE.md
Outdated
|
|
||
| ### Remember | ||
|
|
||
| The goal is to create **practical, actionable security guidance** that helps practitioners build more secure applications and systems. Focus on providing value to your target audience and maintaining high quality standards. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we should mention "concise" somewhere
README.md
Outdated
| ## Contributions, Feature Requests, and Feedback | ||
|
|
||
| We are actively inviting new contributors! To start, please read the [contribution guide](CONTRIBUTING.md). | ||
| We are actively inviting new contributors! To start, please read the [contribution guide](CONTRIBUTING.md) and our comprehensive [How To Make A Cheatsheet guide](GUIDELINE.md). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| We are actively inviting new contributors! To start, please read the [contribution guide](CONTRIBUTING.md) and our comprehensive [How To Make A Cheatsheet guide](GUIDELINE.md). | |
| We are actively inviting new contributors! To start, please read the [contribution guide](CONTRIBUTING.md) and our [How To Make A Cheatsheet guide](GUIDELINE.md). |
|
Alright, this is much cleaner and simpler to consume. Please let me know if I need to make any other changes. |
|
@packtman Getting closer! I left a few more comments |
Done, let me know if this looks good now. |
|
Thank you @szh and @mackowski for taking "lead review" roles on this. I support whatever decisions you both agree to. Any thank you to everyone else for working on this! |
|
Hey everyone, please let me know if the changes look good. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
|
Oops, I missed that the linter is failing: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM. @mackowski will need your approval as well
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
not needed such a change
Issue Reference #1745
Summary
Added a comprehensive "How To Make A Cheatsheet" guide to help contributors create effective security cheat sheets.
Changes Made
GUIDELINE.mdwith detailed guidance for cheat sheet creationREADME.mdto reference the new guideCONTRIBUTING.mdto reference the new guideBenefits