From: Roman Scherer <roman.scherer@burningswell.com>
To: Philip Kaludercic <philipk@posteo.net>
Cc: emacs-devel@gnu.org, ahyatt@gmail.com
Subject: Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized
Date: Mon, 29 Apr 2024 09:44:25 +0200 [thread overview]
Message-ID: <87edao1uli.fsf@burningswell.com> (raw)
In-Reply-To: <87r0eon1i1.fsf@posteo.net> (Philip Kaludercic's message of "Mon, 29 Apr 2024 06:09:42 +0000")
[-- Attachment #1: Type: text/plain, Size: 2446 bytes --]
Hi Philip,
Philip Kaludercic <philipk@posteo.net> writes:
>
> The different files have different audiences. I'd say:
>
> - The README is an introduction to anyone who just checked out a
> repository (or found it on some Website), and wants to know what it is
> about. It should just be a starting point, linking to other resources
> (INSTALL, COPYING, ChangeLog, proper documentation, ...) where
> possible.
>
> - The documentation is for people who have installed a package and want
> to know the exact details of how something works or is done. It is
> not something that would usually interest someone who hasn't
> downloaded and installed a package.
>
> - The package description (C-h P foo RET) is a brief explanation of what
> a package does and provides. It should focus on the questions the
> user might have when they first encounter the package:
>
> * If the name is not indicative, what is the package even about.
>
> * What is the core functionality and how is it used.
>
> * Who is the target audience.
>
> * What are the entry points to the package.
>
> * What differentiates the package from other similar packages.
>
> or other questions like these. It should NOT include:
>
> * A table of contents
>
> * Installation instructions of any kind (there is a install button in
> the package description buffer)
>
> * Extensive details on how to configure the package
>
> * Screenshots, as these are currently not displayed
>
> * Changelog information
>
> and instead try and to keep it short and simple. It is just a sales
> pitch, not a lecture.
>
> Sadly a number of packages just use the same README.org file for all
> these things, confusing the separate audiences. If anything, it is
> acceptable to mix the first two, but the third should certainly not
> result in a 500+ line buffer (as is currently the case with "plz"). The
> easiest way to address the last point is just to use the commentary
> section in the main file to generate the description of the package,
> which we can configure in elpa.git.
Ok, thanks for the explanation. I will then split the README and the
manual up. I will do this in the next days.
I looked a bit around and will probably do something similar to what
Protesilaos does in his packages. This one being an example:
https://github.com/protesilaos/ef-themes
Roman
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 528 bytes --]
next prev parent reply other threads:[~2024-04-29 7:44 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-27 9:02 Add plz-media-type and plz-event-source to GNU ELPA when stabilized Roman Scherer
2024-04-27 13:43 ` Philip Kaludercic
2024-04-28 12:56 ` Roman Scherer
2024-04-29 6:09 ` Philip Kaludercic
2024-04-29 7:44 ` Roman Scherer [this message]
2024-04-29 7:46 ` Philip Kaludercic
2024-04-29 7:48 ` Roman Scherer
2024-04-29 18:24 ` Add plz-media-type and plz-event-source to GNU ELPA when stabilised Philip Kaludercic
2024-04-29 20:17 ` Roman Scherer
2024-05-01 11:25 ` Roman Scherer
2024-05-01 11:56 ` Philip Kaludercic
2024-05-01 12:00 ` Roman Scherer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87edao1uli.fsf@burningswell.com \
--to=roman.scherer@burningswell.com \
--cc=ahyatt@gmail.com \
--cc=emacs-devel@gnu.org \
--cc=philipk@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.