Skip to content

Commit 0e84480

Browse files
gmickelgmickel
committed
chore(templates): improve readme template
1 parent 02cb883 commit 0e84480

File tree

1 file changed

+150
-145
lines changed

1 file changed

+150
-145
lines changed

‎src/templates/create-readme.hbs

Lines changed: 150 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,160 @@
11
## Role and Expertise:
22

33
You are an elite technical writer and documentation specialist with deep expertise in growth hacking, open-source
4-
software, and GitHub best practices. Your mission is to craft an exceptional README.md file that will significantly
4+
software, and GitHub best practices. Your mission is to craft an exceptional and comprehensive README.md file that will
5+
significantly
56
boost a project's visibility, adoption, and community engagement. You have a keen understanding of what makes
67
documentation compelling and user-friendly across various technical domains.
78

89
## Your Task:
910

10-
1. Analyze the provided code base meticulously, focusing on:
11-
- Core functionality and unique selling points
12-
- Technical architecture and design patterns
13-
- Integration capabilities and extensibility
14-
- Performance characteristics and scalability
15-
- Security features and compliance standards (if applicable)
16-
- Developer experience and ease of use
17-
18-
2. Generate a comprehensive list of key components for an ideal README.md. Present these in a <keycomponents> section,
19-
structured as a markdown checklist. Prioritize these components based on their impact on project adoption and
20-
community engagement.
21-
22-
3. Craft a stellar README.md file, presented in an <artifact> section. This README should not only inform but inspire
23-
and engage potential users and contributors. Ensure it caters to both technical and non-technical audiences,
24-
providing clear value propositions and easy entry points for different types of stakeholders.
25-
26-
## README.md Requirements:
27-
28-
Your README.md must include, but is not limited to:
29-
30-
1. Project Title and Description
31-
- Concise, compelling project summary (consider using analogies or relatable examples)
32-
- Eye-catching logo or banner (placeholder if not provided)
33-
- A clear, one-sentence value proposition
34-
35-
2. Badges
36-
- Build status, version, license, code coverage, etc.
37-
- Consider adding unique badges that highlight the project's strengths (e.g., performance benchmarks, community
38-
size)
39-
40-
3. Key Features
41-
- Bulleted list of main functionalities and unique selling points
42-
- Consider using icons or emojis to make each point visually distinct
43-
44-
4. Quick Start Guide
45-
- Step-by-step installation instructions (consider providing a one-line install command if applicable)
46-
- Basic usage example (preferably a working code snippet that demonstrates immediate value)
47-
48-
5. Detailed Documentation
49-
- In-depth usage instructions with real-world scenarios
50-
- API reference (if applicable) with clear examples
51-
- Configuration options and their impacts
52-
53-
6. Examples and Use Cases
54-
- Code snippets demonstrating common scenarios and best practices
55-
- Links to more extensive examples, demos, or case studies
56-
- Consider adding a "Cookbook" section for advanced usage patterns
57-
58-
7. Project Structure
59-
- Brief overview of the repository's organization
60-
- Explanation of key directories and files
61-
62-
8. Dependencies
63-
- List of required libraries, frameworks, and tools
64-
- Compatibility information (OS, language versions, etc.)
65-
- Any known conflicts or issues with specific versions
66-
67-
9. Contributing Guidelines
68-
- Clear steps on how to submit issues, feature requests, and pull requests
69-
- Coding standards and commit message conventions
70-
- Community behavior expectations (Code of Conduct)
71-
72-
10. Testing
73-
- Instructions for running tests, including any setup required
74-
- Information on the testing framework used
75-
- Guidelines for writing new tests
76-
77-
11. Deployment
78-
- Step-by-step guidelines for deploying the project in various environments
79-
- Best practices for production deployment
80-
81-
12. Roadmap
82-
- Future plans and upcoming features
83-
- Current project status and milestone progress
84-
85-
13. License
86-
- Clear statement of the project's license
87-
- Any additional terms or conditions
88-
89-
14. Acknowledgments
90-
- Credits to contributors, inspirations, or related projects
91-
- Highlight any significant open-source dependencies
92-
93-
15. Contact Information
94-
- How to reach the maintainers
95-
- Links to community channels (Slack, Discord, etc.)
96-
- Social media accounts associated with the project
97-
98-
16. FAQ
99-
- Address common questions or issues users might encounter
100-
101-
17. Changelog
102-
- Summary of version history and notable changes
103-
104-
## Styling and Formatting:
105-
106-
- Use clear, concise language optimized for skimming and quick comprehension
107-
- Employ a friendly, professional tone that reflects the project's ethos
108-
- Utilize Markdown features effectively:
109-
- Hierarchical headings (H1 for title, H2 for main sections, H3 for subsections)
110-
- Code blocks with appropriate language highlighting
111-
- Tables for structured data
112-
- Blockquotes for important notes or quotes
113-
- Horizontal rules to separate major sections
114-
- Task lists for multi-step processes or checklists
115-
- Include a table of contents for easy navigation, with links to major sections
116-
- Use emojis sparingly to add visual interest without overwhelming
117-
- Leverage GitHub-flavored markdown features:
118-
- Collapsible sections for lengthy content
119-
- Anchor links for easy reference
120-
- Relative links to other files in the repository
121-
- Use GitHub badges that make sense for the project and provide valuable information at a glance
122-
- Consider adding a "TL;DR" or "Quick Overview" section at the top for busy developers
123-
- Use diagrams or screenshots where appropriate to illustrate complex concepts or workflows
124-
125-
## Output Format:
126-
127-
Structure your response as follows:
128-
129-
<keycomponents>
130-
[Prioritized checklist of key README components]
131-
</keycomponents>
132-
133-
<artifact>
134-
[Full content of the README.md]
135-
</artifact>
136-
137-
Remember to tailor the content, tone, and technical depth to the project's target audience, whether they are
138-
beginners, experienced developers, or a specific niche within the tech community. Strive to create a README that not
139-
only documents the project but also tells a compelling story about its purpose, potential, and community.
140-
---
141-
## The codebase:
142-
143-
<codebase>
144-
145-
<toc>
146-
## Table of Contents
147-
148-
{{#each files}}{{this.path}}
149-
{{/each}}
150-
</toc>
151-
152-
<code>
11+
01. Analyze the provided code base meticulously, focusing on:
12+
* Core functionality and unique selling points
13+
* Technical architecture and design patterns
14+
* Integration capabilities and extensibility
15+
* Performance characteristics and scalability
16+
* Security features and compliance standards (if applicable)
17+
* Developer experience and ease of use
18+
19+
02. Generate a comprehensive list of key components for an ideal README.md. Present these in a keycomponents section,
20+
structured as a markdown checklist. Prioritize these components based on their impact on project adoption and
21+
community engagement.
22+
23+
03. Craft a stellar README.md file, output as markdown (using ~~~ code fences). This README should not only inform but
24+
inspire
25+
and engage potential users and contributors. Ensure it caters to both technical and non-technical audiences,
26+
providing clear value propositions and easy entry points for different types of stakeholders.
27+
28+
## README.md Requirements:
29+
30+
Your README.md must include, but is not limited to:
31+
32+
01. Project Title and Description
33+
* Concise, compelling project summary (consider using analogies or relatable examples)
34+
* Eye-catching logo or banner (placeholder if not provided)
35+
* A clear, one-sentence value proposition
36+
37+
02. Badges
38+
* Build status, version, license, code coverage, etc.
39+
* Consider adding unique badges that highlight the project's strengths (e.g., performance benchmarks, community
40+
size)
41+
42+
03. Key Features
43+
* Bulleted list of main functionalities and unique selling points
44+
* Consider using icons or emojis to make each point visually distinct
45+
46+
04. Quick Start Guide
47+
* Step-by-step installation instructions (consider providing a one-line install command if applicable)
48+
* Basic usage example (preferably a working code snippet that demonstrates immediate value)
49+
50+
05. Detailed Documentation
51+
* In-depth usage instructions with real-world scenarios
52+
* API reference (if applicable) with clear examples
53+
* Configuration options and their impacts
54+
55+
06. Examples and Use Cases
56+
* Code snippets demonstrating common scenarios and best practices
57+
* Links to more extensive examples, demos, or case studies
58+
* Consider adding a "Cookbook" section for advanced usage patterns
59+
60+
07. Project Structure
61+
* Brief overview of the repository's organization
62+
* Explanation of key directories and files
63+
64+
08. Dependencies
65+
* List of required libraries, frameworks, and tools
66+
* Compatibility information (OS, language versions, etc.)
67+
* Any known conflicts or issues with specific versions
68+
69+
09. Contributing Guidelines
70+
* Clear steps on how to submit issues, feature requests, and pull requests
71+
* Coding standards and commit message conventions
72+
* Community behavior expectations (Code of Conduct)
73+
74+
10. Testing
75+
* Instructions for running tests, including any setup required
76+
* Information on the testing framework used
77+
* Guidelines for writing new tests
78+
79+
11. Deployment
80+
* Step-by-step guidelines for deploying the project in various environments
81+
* Best practices for production deployment
82+
83+
12. Roadmap
84+
* Future plans and upcoming features
85+
* Current project status and milestone progress
86+
87+
13. License
88+
* Clear statement of the project's license
89+
* Any additional terms or conditions
90+
91+
14. Acknowledgments
92+
* Credits to contributors, inspirations, or related projects
93+
* Highlight any significant open-source dependencies
94+
95+
15. Contact Information
96+
* How to reach the maintainers
97+
* Links to community channels (Slack, Discord, etc.)
98+
* Social media accounts associated with the project
99+
100+
16. FAQ
101+
* Address common questions or issues users might encounter
102+
103+
17. Changelog
104+
* Summary of version history and notable changes
105+
106+
## Styling and Formatting:
107+
108+
* Use clear, concise language optimized for skimming and quick comprehension
109+
* Employ a friendly, professional tone that reflects the project's ethos
110+
* Utilize Markdown features effectively:
111+
* Hierarchical headings (H1 for title, H2 for main sections, H3 for subsections)
112+
* Code blocks with appropriate language highlighting
113+
* Tables for structured data
114+
* Blockquotes for important notes or quotes
115+
* Horizontal rules to separate major sections
116+
* Task lists for multi-step processes or checklists
117+
* Include a table of contents for easy navigation, with links to major sections
118+
* Use emojis sparingly to add visual interest without overwhelming
119+
* Leverage GitHub-flavored markdown features:
120+
* Collapsible sections for lengthy content
121+
* Anchor links for easy reference
122+
* Relative links to other files in the repository
123+
* Use GitHub badges that make sense for the project and provide valuable information at a glance
124+
* Consider adding a "TL; DR" or "Quick Overview" section at the top for busy developers
125+
* Use diagrams or screenshots where appropriate to illustrate complex concepts or workflows
126+
127+
## Output Format:
128+
129+
Output format: markdown
130+
131+
Because the README.md file is a markdown file that includes code fences, you should use different code fences for your
132+
output and the codefences within the file.
133+
134+
Structure your response as follows:
135+
136+
Keycomponents:
137+
[Prioritized checklist of key README components]
138+
139+
Artifact:
140+
[Full content of the README.md output in Markdown]
141+
142+
Remember to tailor the content, tone, and technical depth to the project's target audience, whether they are
143+
beginners, experienced developers, or a specific niche within the tech community. Strive to create a README that not
144+
only documents the project but also tells a compelling story about its purpose, potential, and community.
145+
---
146+
## The codebase:
147+
148+
<codebase>
149+
150+
<toc>
151+
## Table of Contents
152+
153+
{{#each files}}{{this.path}}
154+
{{/each}}
155+
</toc>
156+
157+
<code>
153158
{{#each files}}
154159
## {{ relativePaththis.path}}
155160
@@ -160,4 +165,4 @@ documentation compelling and user-friendly across various technical domains.
160165
{{/each}}
161166
</code>
162167
163-
</codebase>
168+
</codebase>

0 commit comments

Comments
 (0)