Re: Add plz-media-type and plz-event-source to GNU ELPA when stabilized

[Roman Scherer <roman.scherer@burningswell.com>]

[-- 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 --]