quick readme guide draft

Author: essential-randomness

astro.config.mjs

@@ -26,6 +26,10 @@ export default defineConfig({
           label: "FujoWeb.dev & FujoGuide",
           autogenerate: { directory: "fujowebdev" },
         },
+        {
+          label: "GitHub",
+          autogenerate: { directory: "github" },
+        },
       ],
     }),
   ],

src/content/docs/github/writing-readmes.mdx

@@ -0,0 +1,113 @@
+---
+title: How to write READMEs
+description: A guide in my new Starlight docs site.
+---
+
+## 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