Dart. Dev /guides/libr…

Original author:

Release date: May 4, 2021

The guide on this page can help you create good package pages on pub.dev. Specifically, this page has hints for writing a better package README, which provides the README (this document) highlighted in the screenshot below.

The package page contains the following sections: package layout, Flutter favorites, package ratings, verified publishers, and PubSpec files

For details on other parts of the package page, follow these links.

  1. The layout of the package
  2. Because love
  3. Package of score
  4. A verified publisher
  5. Press release document

Writing a good README is important

The person who finds your package on pub.dev will most likely do a quick scan of README when deciding whether to try your package. A good README grabs the reader’s attention and shows that your package is worth a try.

Note: The package’s README can be used in a number of ways. For example, its contents appear not only in the package page on pub.dev, but also in the API reference documentation produced by DartDoc.

While this page features a README for the in_app_purchase package, your package probably doesn’t need to be that big or that detailed. If your package is simple and has no associated user interface, its README might look more like the yamL package’s.

Seven tips for good README

Here are some suggestions for creating a README that works well on pub.dev.

  1. Put a short description at the top
  2. Including visual content
  3. Use lists to present important information
  4. Examples
  5. Use the Dart code for formatting
  6. Refer to related terms
  7. Tell the user what to do next

1. Put a short description at the top

According to our user research, users of the package spend only a few seconds reading the package’s description and deciding whether to read the rest of the README. Therefore, you should succinctly describe what the package does or implements at a glance. Take the time to craft a short, sweet description to help the user make a decision.

Prompt. Do not write the name of the package at the top. It is already visible in pub.dev UI.

Here are some examples of good descriptions.

  • A Flutter plugin for displaying rainbows.
  • Using machine learning to classify bird sounds.

Important information, such as project status or constraints, should also be placed near the top. For example.

  • Does not apply to iOS versions earlier than 10.3.

Below is a screenshot of the in_app_Purchase package page, which begins with a brief explanation of the package and considerations.

The badge is usually near the top of the README, above or below the short description.

2. Include visual content

If your package page is a wall of text with no visual content, users may find it intimidating and stop reading. Images are especially important if your package supports user interfaces, but they are also useful to explain important concepts. However, visual content can help users feel confident about using the package.

Place visual content such as still images, GIF animations, and videos (such as MOV or MP4 files) near the beginning of the README so users can see them.

Prompt. Gifs and videos are best when it comes to user interfaces, because most user interfaces are not static, and animations can convey more information about user interface behavior.

The screenshot below shows how adding visual content makes the wrapper page for IN_app_Purchase appear informative at first glance. (On the left is the previous image; On the right is the later image).

Tip: When adding visual content, use absolute urls for files so that images appear reliably, no matter where the README is published. There is a place to store your images, as in_app_purchase does, in the version library itself.

3. Use lists to present important information

Lists draw attention to important information in the README. You can use lists in the following ways.

  • Main features of a software package
  • Parameter, attribute, or attribute
  • Unusual request
  • Functions beyond the scope of your package
  • A summary of the content of a page or section of a page (such as this list).

Usually, lists are bulleted, like the one above. Another option is to use tables, like the platform support tables in the next section.

Main features of the software package

First, make a clear list of what your package can do. Some users may be looking for a very specific feature. Help these users find out if your package supports their needs.

The screenshot below shows how the README for in_app_Purchase describes the functionality of the package.

The next screenshot shows a table in the Just_Audio README that lists the package’s features and platform support.

Parameter, property, or property

Consider listing parameters, attributes, or features for quick reference. (Remember, the contents of the package README appear in the API reference documentation, as well as on the package page).

For example, the URl_launcher package has a table that supports the URL scheme.

Links to specific functions or classes in the API reference documentation can also be useful. See an example of the Async package.

Unusual request

If your package requires a specific setting that goes beyond what all packages require, list the setting instructions in the README.

For example, here is a screenshot of the Google_maps_FLUTTER package, showing instructions about starting to use the Google Maps platform.

Features that are not within the scope of your package

To help users understand whether your package can help them, make a list of features that users might expect that your package does not support.

Here are some examples of features that you might want to list out of scope.

  • If your button pack only focuses on text buttons and doesn’t support icon buttons, make that clear in README.
  • If your package only supports certain versions of Android, say so in README.

content

When a page or chapter has a table of contents, users find it easier to navigate. If a section of your README is very long, consider listing the sections clearly at the beginning of the section.

For example, the “usage” section of the in_app_Purchase README has many examples. The following table of contents helps users understand what examples exist and navigate to the code they are interested in.

4. Use examples are included

If your package looks promising, users may want to test your package. Include a “get started” or “use” section with at least one code sample that users can easily understand — and, preferably, that they can copy and paste into their project. If you can provide more examples and more detail to help users understand your package, so much the better.

Keep in mind that not all users speak English, but they all speak Dart! Good code samples can go a long way. Consider adding more complete examples to your package’s examples directory, which pub.dev can use to populate the examples TAB. See the example package layout convention for details.

The screenshot below shows one of several examples from the README of the in_app_purchase package.

5. Use the Dart code for formatting

When adding code examples, use three back signs plus dart (DART) instead of three back signs (). As shown in the example below, adding DART tells pub.dev to use dart syntax highlighting.

Use only formatting

final like = 'this';
Copy the code

Use dart formatting

final like = 'this';
Copy the code

6. Mention relevant terms

A recent user experience study found that many users use the in-page search feature (Control+F or Command+F) to search for the feature they are looking for. Therefore, be sure to include important terms in the README so that users can find them.

For example, a user might want to know if the in_app_purchase package supports in-app subscriptions. If a page does not use the term, users searching for subscriptions may abandon the page.

After mentioning all the terms people might search for, be consistent with the terms you use. Define these terms clearly if necessary.

For example, the in_app_purchase package defines the underlying store at the beginning.

The rest of the page uses the term consistently.

7. Tell users where to go next

Help your users find out more about the package. Here are some tips for telling potential users.

  • Where can I learn more about this package? You can link to an article on Medium, or to a video on YouTube.
  • Where to get help on using the package. This might include a question tracker, a chat room, or an E-mail address.
  • What are you going to do with this bag? A roadmap — in a README or external page — helps users know if the features they need are coming.
  • How to contribute code to a software package.

The screenshot below shows the part of the IN_app_Purchase README that provides information for potential contributors.

Learn more about good README writing

We present seven tips for a good README in this document. You can learn more about common advice on developer documentation from the Google Developer Documentation Style Guide. Some additional tips are included.

  • Provide Alt text for images.
  • To the point. Don’t say please.
  • Keep the line length <=80 characters.
  • Properly format code (e.g. Dartfmt or FLUTTER format).

To learn more about README good practices, see these resources.

Write a README checklist to help readers have confidence in your project.

Good README A curated, annotated list of good README.

Making README An introduction to README, including a template and suggestions for a good README.

How to write a good README for your GitHub project The key elements of a good README, as well as a template.

The recommendations on this page and others may not be appropriate for all packages. Be creative! Put yourself in the user’s shoes and imagine what the reader might want to read and know. You are the only one who can provide the information the reader needs.

Translation via www.DeepL.com/Translator (free version)