Re: [Audacity-quality] Manual: Section Header Consistency

[Peter S. <pet...@gm...>]

On Sat, Apr 3, 2021 at 8:34 AM Peter Sampson <pet...@gm...>
wrote:

>
>
> On Sat, Apr 3, 2021 at 12:54 AM Pokechu22 <
> pok...@gm...> wrote:
>
>> That's because the first one is just a regular header (== Time Scale
>> Zooming (Horizontally) ==), but the second one has a link in it (==
>> [[Vertical Zooming]] ==).  They're at the same heading level (and thus
>> have the same font size and boldness); the color is only from the link.
>>
>> I don't know what Audacity's style guide is for these (it does seem to be
>> used in several places on that page at least), but Wikipedia discourages
>> them (see https://en.wikipedia.org/wiki/MOS:NOSECTIONLINKS - though that
>> doesn't elaborate on why they aren't recommended).
>>
>
> Frankly, speaking as the primary Manual editor, I am not too concerned
> with Wikipedia's
> policy on this *(except when I am editing Wikipedia as a minor
> Wikipedian)* and see no need
> to slavishly follow Wikipedia's style guide in our Audacity documentation.
>
> I use links in headers to aid users - I do that to make life easier for
> them.
>
> I will have a look later today to see what Connie (our style guide) says
> about this, *but*
> *she may end up ruling in favor  ;-)*
>

Basically Connie currently has no ruling one way or the other about links
in headers:
https://alphamanual.audacityteam.org/man/Consistency#Layout

I do note that she says:
> Generally, we stick to Wikipedia guidelines
<http://en.wikipedia.org/wiki/Wikipedia:Naming_conventions_%28capitalization%29>
for page titles.

But:
a) note that applies specifically to "page titles (and we observe that)

b) note carefully the use of "Generally" which allows for some occasional
flexibility
if and when thought about.

She's going to ponder the headings with links issue today, but I'm
suspecting that
she'll come down in favour of allowing such links ( for a start there are
many of those
scatterd throughout the Manual.

One of the reasons that I, as editor, like these headers with links is that
is is a clear visual
cue to the reader that there is a page or section elsewhere in the Manual
that contains a
lot more detailed information then the text they are currently reading.

One of the underlying design features of the Manual is that it rests
heavily on the use of
hyper-text with thousands of links throughout the Manual - starting, of
course, with Bill's
"*Amazing Image-map*" that we have on the front page (acting effectively as
a "Contents"
directory).

Peter.




>
> Peter.
>
>
>
>> --Poke
>>
>> On Fri, Apr 2, 2021 at 4:44 PM John Colket <jc...@gm...> wrote:
>>
>>> These two manual links should be at the same heading level, but display
>>> in different colors on Chrome:
>>>
>>> https://manual.audacityteam.org/man/zooming.html#horizontal
>>> https://manual.audacityteam.org/man/zooming.html#vertical
>>>
>>> - John
>>>
>>>
>>>
>>> _______________________________________________
>>> Audacity-quality mailing list
>>> Aud...@li...
>>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>>
>> _______________________________________________
>> Audacity-quality mailing list
>> Aud...@li...
>> https://lists.sourceforge.net/lists/listinfo/audacity-quality
>>
>