Skip to content

Commit

Permalink
chore(templates): improve readme template
Browse files Browse the repository at this point in the history
  • Loading branch information
@gmickel
gmickel committed Jul 21, 2024
1 parent 02cb883 commit 0e84480
Showing 1 changed file with 150 additions and 145 deletions.
295 changes: 150 additions & 145 deletions src/templates/create-readme.hbs
View file
Original file line number Diff line number Diff line change
@@ -1,155 +1,160 @@
## Role and Expertise:

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

## Your Task:

1. Analyze the provided code base meticulously, focusing on:
- Core functionality and unique selling points
- Technical architecture and design patterns
- Integration capabilities and extensibility
- Performance characteristics and scalability
- Security features and compliance standards (if applicable)
- Developer experience and ease of use

2. Generate a comprehensive list of key components for an ideal README.md. Present these in a <keycomponents> section,
structured as a markdown checklist. Prioritize these components based on their impact on project adoption and
community engagement.

3. Craft a stellar README.md file, presented in an <artifact> section. This README should not only inform but inspire
and engage potential users and contributors. Ensure it caters to both technical and non-technical audiences,
providing clear value propositions and easy entry points for different types of stakeholders.

## README.md Requirements:

Your README.md must include, but is not limited to:

1. Project Title and Description
- Concise, compelling project summary (consider using analogies or relatable examples)
- Eye-catching logo or banner (placeholder if not provided)
- A clear, one-sentence value proposition

2. Badges
- Build status, version, license, code coverage, etc.
- Consider adding unique badges that highlight the project's strengths (e.g., performance benchmarks, community
size)

3. Key Features
- Bulleted list of main functionalities and unique selling points
- Consider using icons or emojis to make each point visually distinct

4. Quick Start Guide
- Step-by-step installation instructions (consider providing a one-line install command if applicable)
- Basic usage example (preferably a working code snippet that demonstrates immediate value)

5. Detailed Documentation
- In-depth usage instructions with real-world scenarios
- API reference (if applicable) with clear examples
- Configuration options and their impacts

6. Examples and Use Cases
- Code snippets demonstrating common scenarios and best practices
- Links to more extensive examples, demos, or case studies
- Consider adding a "Cookbook" section for advanced usage patterns

7. Project Structure
- Brief overview of the repository's organization
- Explanation of key directories and files

8. Dependencies
- List of required libraries, frameworks, and tools
- Compatibility information (OS, language versions, etc.)
- Any known conflicts or issues with specific versions

9. Contributing Guidelines
- Clear steps on how to submit issues, feature requests, and pull requests
- Coding standards and commit message conventions
- Community behavior expectations (Code of Conduct)

10. Testing
- Instructions for running tests, including any setup required
- Information on the testing framework used
- Guidelines for writing new tests

11. Deployment
- Step-by-step guidelines for deploying the project in various environments
- Best practices for production deployment

12. Roadmap
- Future plans and upcoming features
- Current project status and milestone progress

13. License
- Clear statement of the project's license
- Any additional terms or conditions

14. Acknowledgments
- Credits to contributors, inspirations, or related projects
- Highlight any significant open-source dependencies

15. Contact Information
- How to reach the maintainers
- Links to community channels (Slack, Discord, etc.)
- Social media accounts associated with the project

16. FAQ
- Address common questions or issues users might encounter

17. Changelog
- Summary of version history and notable changes

## Styling and Formatting:

- Use clear, concise language optimized for skimming and quick comprehension
- Employ a friendly, professional tone that reflects the project's ethos
- Utilize Markdown features effectively:
- Hierarchical headings (H1 for title, H2 for main sections, H3 for subsections)
- Code blocks with appropriate language highlighting
- Tables for structured data
- Blockquotes for important notes or quotes
- Horizontal rules to separate major sections
- Task lists for multi-step processes or checklists
- Include a table of contents for easy navigation, with links to major sections
- Use emojis sparingly to add visual interest without overwhelming
- Leverage GitHub-flavored markdown features:
- Collapsible sections for lengthy content
- Anchor links for easy reference
- Relative links to other files in the repository
- Use GitHub badges that make sense for the project and provide valuable information at a glance
- Consider adding a "TL;DR" or "Quick Overview" section at the top for busy developers
- Use diagrams or screenshots where appropriate to illustrate complex concepts or workflows

## Output Format:

Structure your response as follows:

<keycomponents>
[Prioritized checklist of key README components]
</keycomponents>

<artifact>
[Full content of the README.md]
</artifact>

Remember to tailor the content, tone, and technical depth to the project's target audience, whether they are
beginners, experienced developers, or a specific niche within the tech community. Strive to create a README that not
only documents the project but also tells a compelling story about its purpose, potential, and community.
---
## The codebase:

<codebase>

<toc>
## Table of Contents

{{#each files}}{{this.path}}
{{/each}}
</toc>

<code>
01. Analyze the provided code base meticulously, focusing on:
* Core functionality and unique selling points
* Technical architecture and design patterns
* Integration capabilities and extensibility
* Performance characteristics and scalability
* Security features and compliance standards (if applicable)
* Developer experience and ease of use

02. Generate a comprehensive list of key components for an ideal README.md. Present these in a keycomponents section,
structured as a markdown checklist. Prioritize these components based on their impact on project adoption and
community engagement.

03. Craft a stellar README.md file, output as markdown (using ~~~ code fences). This README should not only inform but
inspire
and engage potential users and contributors. Ensure it caters to both technical and non-technical audiences,
providing clear value propositions and easy entry points for different types of stakeholders.

## README.md Requirements:

Your README.md must include, but is not limited to:

01. Project Title and Description
* Concise, compelling project summary (consider using analogies or relatable examples)
* Eye-catching logo or banner (placeholder if not provided)
* A clear, one-sentence value proposition

02. Badges
* Build status, version, license, code coverage, etc.
* Consider adding unique badges that highlight the project's strengths (e.g., performance benchmarks, community
size)

03. Key Features
* Bulleted list of main functionalities and unique selling points
* Consider using icons or emojis to make each point visually distinct

04. Quick Start Guide
* Step-by-step installation instructions (consider providing a one-line install command if applicable)
* Basic usage example (preferably a working code snippet that demonstrates immediate value)

05. Detailed Documentation
* In-depth usage instructions with real-world scenarios
* API reference (if applicable) with clear examples
* Configuration options and their impacts

06. Examples and Use Cases
* Code snippets demonstrating common scenarios and best practices
* Links to more extensive examples, demos, or case studies
* Consider adding a "Cookbook" section for advanced usage patterns

07. Project Structure
* Brief overview of the repository's organization
* Explanation of key directories and files

08. Dependencies
* List of required libraries, frameworks, and tools
* Compatibility information (OS, language versions, etc.)
* Any known conflicts or issues with specific versions

09. Contributing Guidelines
* Clear steps on how to submit issues, feature requests, and pull requests
* Coding standards and commit message conventions
* Community behavior expectations (Code of Conduct)

10. Testing
* Instructions for running tests, including any setup required
* Information on the testing framework used
* Guidelines for writing new tests

11. Deployment
* Step-by-step guidelines for deploying the project in various environments
* Best practices for production deployment

12. Roadmap
* Future plans and upcoming features
* Current project status and milestone progress

13. License
* Clear statement of the project's license
* Any additional terms or conditions

14. Acknowledgments
* Credits to contributors, inspirations, or related projects
* Highlight any significant open-source dependencies

15. Contact Information
* How to reach the maintainers
* Links to community channels (Slack, Discord, etc.)
* Social media accounts associated with the project

16. FAQ
* Address common questions or issues users might encounter

17. Changelog
* Summary of version history and notable changes

## Styling and Formatting:

* Use clear, concise language optimized for skimming and quick comprehension
* Employ a friendly, professional tone that reflects the project's ethos
* Utilize Markdown features effectively:
* Hierarchical headings (H1 for title, H2 for main sections, H3 for subsections)
* Code blocks with appropriate language highlighting
* Tables for structured data
* Blockquotes for important notes or quotes
* Horizontal rules to separate major sections
* Task lists for multi-step processes or checklists
* Include a table of contents for easy navigation, with links to major sections
* Use emojis sparingly to add visual interest without overwhelming
* Leverage GitHub-flavored markdown features:
* Collapsible sections for lengthy content
* Anchor links for easy reference
* Relative links to other files in the repository
* Use GitHub badges that make sense for the project and provide valuable information at a glance
* Consider adding a "TL; DR" or "Quick Overview" section at the top for busy developers
* Use diagrams or screenshots where appropriate to illustrate complex concepts or workflows

## Output Format:

Output format: markdown

Because the README.md file is a markdown file that includes code fences, you should use different code fences for your
output and the codefences within the file.

Structure your response as follows:

Keycomponents:
[Prioritized checklist of key README components]

Artifact:
[Full content of the README.md output in Markdown]

Remember to tailor the content, tone, and technical depth to the project's target audience, whether they are
beginners, experienced developers, or a specific niche within the tech community. Strive to create a README that not
only documents the project but also tells a compelling story about its purpose, potential, and community.
---
## The codebase:
<codebase>
<toc>
## Table of Contents
{{#each files}}{{this.path}}
{{/each}}
</toc>
<code>
{{#each files}}
## {{ relativePaththis.path}}
Expand All @@ -160,4 +165,4 @@ documentation compelling and user-friendly across various technical domains.
{{/each}}
</code>
</codebase>
</codebase>

0 comments on commit 0e84480

Please sign in to comment.