DocTeam page edit request

[Little Girl]

Hey there,

Martin Dixon wrote:

> I could find no reaction to this bit however -
 
> Intro -
> There are however a couple of oddities revealed in -
> "is comfortable working with Bazaar, Launchpad, and either Mallard
> <http://projectmallard.org/index.html> for the Ubuntu User Guide or
> DocBook" <https://help.ubuntu.com/community/DocBook>
> where Mallard and DocBook are links Bazaar and Launchpad are not. 
> Neither are they when previously mentioned,
> 
> Question -
> Which raises the general question as to which of all the references
> in the whole document should be words (Mallard) or links (Mallard)
> <http://projectmallard.org/index.html> in the first place?
> 
> Any lessons on that?

That's a good question, and a weighted one, at that! I took a look at
both below. Feel free to add to, edit, or remove any of my benefits
and drawbacks. (:

--------------------

EVERY LOCATION IS A LINK

Benefits:
- More user-friendly since additional information is always a click
  away no matter where a user is in a page.
- You'll always be able to click to visit the location no matter
  where the reference is in a page.

Drawbacks:
- It might give a cluttered or "busy" look to pages, making them
  difficult to read.
- It might make pages difficult to maintain [see related aside
  below] since you'd have to edit all the links manually if they
  change. The search and replace feature of most applications
  nowadays would simplify this, though.

--------------------

THE FIRST LOCATION ON A PAGE IS A LINK AND ALL THE REST ARE PLAIN TEXT

Benefits:
- Pages will be less cluttered and possibly easier to read.
- Less maintenance if links change.

Drawbacks:
- Less user-friendly on pages that are long or divided into
  sub-sections, where a user might not see the link at the top of the
  page or know to go find it.
- We are creatures of habit, and if we usually don't make location
  references into links, it might be hard to remember to make the
  first reference into a link.


[related aside]
I can't help but put in a plug for the simple elegance of DocBook,
where you define a link in one place and then repeatedly call it with
specific syntax elsewhere. If the link changes, you only need to edit
it in the one place, which automatically updates all the rest.

--------------------

-- 
Little Girl

There is no spoon.