Based on our recent customer interviews and surveys, one of the top problems that package consumers face is insufficient package documentation, such as README, changelog, examples, and API reference. On the other hand, package authors may struggle with best practices for creating a clear and concise README. Our goal is to improve the overall experience for both consumers and authors by addressing this issue.

The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. It’s also one of the first things users will see when they view your package on NuGet.org. Therefore, it’s essential for package authors to write a high-quality README.

– Image from MySqlConnector package

High quality READMEs are not limited to a specific format or structure. Instead, it’s about effectively communicating the purpose and functionality of your package to potential users. For this guidance, we would like to share our perspectives on how to write a high-quality README and provide support for package authors who may be unsure about best practices of creating a README. By following our tips and best practices, we hope you can improve the quality of your READMEs and better serve your users.

What may a high-quality README include

Here are some key elements to consider when you write an excellent README:

• Start with a clear and concise description: Start your README with a brief overview of what your package is and does, also what problem it solves.
• Explain how to use it: Provide clear and concise getting started instructions for using your package, including any necessary steps.
• Give examples: Provide concrete examples of how your package can be used to help users quickly understand its capabilities.
• Provide links to more resources: List links such as detailed documentation, tutorial videos, blog posts, or any other relevant documentation to help users get the most out of your package.
• Include screenshots or visuals: Enhance your README by including screenshots, diagrams, or other visual aids that help users better understand how to use your package.
• Write down any limitations: Mention any limitations or known issues with your package and provide workarounds, if available.
• Provide sample code: Provide sample code snippets to help users understand how to implement your package in their projects.
• Make it visually appealing: Use clear headings, code blocks, etc. to make your README appealing and easy to navigate.

README template

Here is a template to get you started with writing a great README for your package.

# Package readme title, e.g., display name or title of the package (optional)

Start with a clear and concise description: A brief overview of what your package is and does, also what problem it solves.

## Getting started

Explain how to use your package, provide clear and concise getting started instructions, including any necessary steps.

### Prerequisites

What are specific minimum requirements to use your packages? Consider excluding this section if your package works without any additional setup beyond simple package installation.

## Usage

Examples about how to use your package by providing code snippets/example images, or samples links on GitHub if applicable. 

- Provide sample code using code snippets
- Include screenshots, diagrams, or other visual help users better understand how to use your package

## Additional documentation

Provide links to more resources: List links such as detailed documentation, tutorial videos, blog posts, or any other relevant documentation to help users get the most out of your package.

## Feedback

Where and how users can leave feedback?

- Links to a GitHub repository where could open issues, Twitter, a Discord channel, bug tracker, or other platforms where a package consumer can connect with the package author.

Examples of high-quality READMEs

As we mentioned earlier, well-written READMEs can come in a wide variety of styles, shapes, and sizes. Here are packages on NuGet.org we found that are well-written and incorporated some best practices:

• Azure.Storage.Blobs
• Azure.Extensions.AspNetCore.Configuration.Secrets
• GitInfo
• MySqlConnector
• System.IO.Abstractions

Other good practices

• API reference: If applicable, link to the package’s API documentation.
• Badges: If applicable, provide code coverage, build status, code quality and so on (NuGet.org supports badges and images from a trusted allow-list of domains, feel free to file an issue if you think another domain should be added to the allow-list, we will review it for security and privacy compliance).

• Table of contents: A README should contain necessary information for package consumers to get started using and where and how to leave feedback. If your README is long with all necessary information, a table of contents may help users navigate the README more easily. You could add links to a section within your README using markdown syntax like below:

  [Text to sub-heading](#text-of-the-subheading)
  

• Troubleshooting: Provide information on how to troubleshoot common issues that users may encounter when using the package.

Additional documentation

• If you are new to NuGet README, learn more about how to add a README to your NuGet Package.
• A list of Markdown features NuGet.org supports.

We want to hear your feedback

Show us your best package README on Twitter with #nugetreadme and we’ll highlight the winners in a future blog!

Your feedback is very important to us. If you experience any issue using READMEs or have ideas for improvements – please feel free to contact us by filing an issue.

For more general NuGet feedback and suggestions:

• Check out our documentation on submitting bugs and suggestions.
• Schedule a time to talk to NuGet.
• Reach out to us on Twitter – mention @nuget in your tweets.