Re: Support for non-free-firmware in project webpages

[Ian Jackson <ijackson@chiark.greenend.org.uk>]

Bill Allombert writes ("Re: Support for non-free-firmware in project webpages"):
> The link in the footer points to a page on SALSA with all the informations
> already.

I had indeed found the page you link to.  But, for me it didn't answer
these questions.  Let me lead you through it.

The popcon.debian.org website page footer says:

  [Popularity-contest project] by Avery Pennarun, Bill Allombert and
  Petter Reinholdtsen.

I did indeed follow that link.  It is a link to

  https://salsa.debian.org/popularity-contest-team/popularity-contest

which starts with

  | The popularity-contest package sets up a cron job that will ...

Then there is some general information about what the popcon system is
for.  So, the reader has been told that the are looking at the data
upload client.

The text you then quote is right at the bottom of that README, which
is 137 lines long.  On my screen it does indeed say, on the 4th page:

> ""
> FINDING THE SOURCE
> ==================
> 
> This package is being maintained in GIT on salsa.debian.org.
       ^^^^^^^
> The project summary page is available from
> <URL:https://salsa.debian.org/popularity-contest-team/popularity-contest>
> The project home page is at <URL:https://popcon.debian.org/>.

Now we are talking about the *package*.

What will not be obvious to many readers is that:

 * The source code to the live popcon.debian.org *website instance*
   is to be found within this *Debian source package*.

 * Change requests *for the website* should be submitted to the
   *package* in the Debian bug system.

Perhaps it seems obvious to you that the source code for the website
would be in the source package containing the upload client.  But that
is not a universal way of organising things.  Indeed, I think,
nowadays, it is slightly unusual [1].

I think it would be better if the page footer explicitly said where
its own source code was.

Indeed, it ought to tell you *where in the source tree* it is.  Since,
it's in the "examples" directory!  After you told us it was in that
git repo, I looked again, and I did I eventually find the source code
for the website - but only by grepping the git repo for strings that
were displayed in my browser.

Amending the text at the bottom of the README would also be good, but
only helps a reader who is quite determined - a casual reader isn't
going to scroll through and skimread many pages of what they will
probably think is an irrelevant document.

Ian.

[1] I do it myself: src:dgit contains the source code for the
server-side.  But the deployed instance is not running from an
installed copy of dgit-infrastructure..deb.

-- 
Ian Jackson <ijackson@chiark.greenend.org.uk>   These opinions are my own.  

Pronouns: they/he.  If I emailed you from @fyvzl.net or @evade.org.uk,
that is a private address which bypasses my fierce spamfilter.