How to write READMEs

Before you start writing

We write our READMEs to be approachable to hobbyists. Keep your words simple, but it’s ok to make assumptions about the technologies they know.
Our libraries are often useful to advanced developers too. Make sure there are sections that speak more directly to their language and needs. Help them skip over basic explanations they don’t need to go to what interests them.

Sections

Intro

Project banner
Few words description of what the library does
Technologies used and other badges

About this library

What does `[library-name]` do?

Simple explanation (couple short sentence) for a fannish person stumbling upon the repo.
A few more sentences that mention technical terms so experienced folks can pattern-match and really understand if it does what they seek.
Make sure you namedrop and link to the relevant technologies. For example, if it’s an Astro Integration, make sure you link to Astro.

Inside you’ll find…

A quick list of the major components of this library. Once again, make sure it’s understandable to a hobbyist for whom the library is relevant.

What can you build with `[library-name]`?

Alternatively: What can you do with [library-name]?

Think about the major categories of applications that the library enables, building from the simplest cases, to those that require more configurations.
List items should state the general concept first, then go into practical examples. For example, “read the data on a visitor’s PDS, so you can create comment sections, or guestbooks, or…”

How to use `[library-name]`

If we have examples, this may be a good place to add a note like “learn better with examples? Skip directly to the examples section (link) or look for them in [folder/path] (link)

Prerequisites

Anything the library assumes is already there. For example, make sure your Astro site is configured, that it has server mode, and have Astro sessions enabled.
If we have any guide that would help getting folks started, this is a good place to link to them.

Installation & Requirements

The install command. We should use npm and assume everyone who’s using a different one is aware they can use another.
If other special libraries must be installed, this is also a place to mention them.
If a library should already be installed by the time a user finds a use for the library, it would go in pre-requisites instead.

Configuring `[library-name]`

Start with easy to follow steps:

Quick steps needed for the base configuration, in numbered bullet points
You don’t have to show everything that’s possible, just do a quick list for the minimum required setup
Try not to skip steps. If something needs e.g. importing, mention it
If choices need to be made, give a quick explanation of what they are and influence, and a reccommendation to get started
You can add optional steps for common use cases

Then do a full example:

Finish with an example, as copy/pastable then easy to fill as possible. For example, prefer writing "your_string_here" to just leaving a comment, so someone who copy pastes can just double click and replace.
In the example, you can reiterate minimum requirements and choices to be made using comments
The example should be simple, but you can add configuration options if it helps illustrate what’s possible, even if they’re not required.

At the end, redirect to a configuration section (or site) for further options. You can tease what those options will enable, so folks know whether it’s worth going there.

If there are multiple independent sections (e.g. configure the client and then configure the server), you should split those up in their own subsections.

Using `[library-name]`

Note that to see this in action, people can go directly to the example folder
Start by highlighting things you get out of the box
If there are more involved usages, create subsections with descriptive titles
Make sure you redirect users to practical examples throughout (link directly to the appropriate lines)

Configuration Options

TODO