`Help Us' section duplicated

[markdblackwell]

The first (front matter) page of the Contributor's Guide manual (version
2.19.23, in the second paragraph) refers people to a very important section,
'Help Us' located in another manual: the Web/General Information manual.

In the PDF version: `For more information about different jobs, see Section
“Help us” in General Information.'

In the HTML version: `For more information about different jobs, see _Help
us_.'

Its underlying HTML (reformatted for clarity) is:

However, currently the Contributor's Guide also incorporates a duplicate
copy of this 'Help us' subsection, plainly visible near the top of the
index. Its text exactly matches that in the Web/General Information manual,
and includes the same, detailed discussions of `Simple tasks' and `Advanced
tasks'.

The duplication extends all the way from:

    Help us/We need you!

down through:

    Bugfixes or new features: read Section “Programming work” in
Contributor’s Guide.

This, combined with referring the reader (as it turns out) to the same
content, yet in another manual, might somewhat confuse readers as to why.
(It did so, for me.)

Also, some readers might be motivated to check whether or not the content
indeed is exactly duplicated (since we don't say so). They might possibly
consider that it could have fallen obsolete in one or another of the copies
(in the usual way).

Question: The first page of the Contributor's Guide, for people who are
considering helping LilyPond, includes a link to `Help us'. Should that link
go to section `Help us' of:

1. The Contributor's Guide manual?; or of

2. The Web/General Information manual?

IMO, best is that:

1. The link should continue to target that same section of the Web/General
Information manual; and

2. The duplicate text in the Contributor's Guide manual should be replaced
by something like:

    Please see Section “Help us” in General Information.

including a link to it (of course).

Alternatively, if actually and currently the repeated text is maintained in
only one place in the source code, perhaps this particular duplication of
text in the manuals can't cause problems.

However, in that case, exactly at that point in the Contributor's Guide, IMO
we briefly should state something like:

    This information is an exact, automatic copy of section `Help us' from
the Web/General Information manual.

None of the other manuals duplicates the `Help us` section text, BTW.



--
View this message in context: 
http://lilypond.1069038.n5.nabble.com/Help-Us-section-duplicated-tp178962.html
Sent from the Bugs mailing list archive at Nabble.com.