RT Ticket #79: Comments on the [usertrack] tag in the DocBook docs

[phinjensen]

Created: Wed Jul 11 22:08:15 2007
Requestors: Kevin Walsh

---

• The reader is directed to "the section called EXAMPLES", to find an
  explanation of what is meant by the "GET-like syle". No explanation is
  given there, or elsewhere on the page.
• In NOTES, it says "[usertrack] does not work on special pages." That
  is incorrect ("flypage" and "results" etc.).
• The link to "special"
  (http://www.icdevgroup.org/glossary/special.html) is broken.
• Same broken link problem on "tracking".
• The SOURCE section doesn't add anything to the documentation and
  should be dropped.

[phinjensen]

Date: Thu Jul 12 06:58:07 2007
Author: Stefan Hornburg

---

Kevin Walsh via RT wrote:

Wed Jul 11 17:08:15 2007: Request 79 was acted upon.
Transaction: Ticket created by kevin
Queue: Documentation
Subject: Comments on the [usertrack] tag in the DocBook docs
Owner: docelic
Requestors: kevin@cursor.biz
Status: new
Ticket <URL: http://rt.icdevgroup.org//Ticket/Display.html?id=79 >

• The reader is directed to "the section called EXAMPLES", to find an
  explanation of what is meant by the "GET-like syle". No explanation is
  given there, or elsewhere on the page.
• In NOTES, it says "[usertrack] does not work on special pages." That
  is incorrect ("flypage" and "results" etc.).
• The link to "special"
  (http://www.icdevgroup.org/glossary/special.html) is broken.
• Same broken link problem on "tracking".

This is a systematic error appearing on all links pointing to the glossary
(#71).

• The SOURCE section doesn't add anything to the documentation and
  should be dropped.

Do you think the SOURCE section doesn't add anything to the documentation in general
or just not for [usertrack] ?

Regards
Racke

[phinjensen]

Date: Thu Jul 12 09:04:53 2007
Author: Kevin Walsh

---

Do you think the SOURCE section doesn't add anything to the
documentation in general
or just not for [usertrack] ?

In general. I think it might be useful for filters and other similar
small blocks of code but, only if the code helps to understand the
documentation text.

In this case, the source section shows nothing useful at all. Most of
the config directives have the same problem (no useful code in the
source section), as does a few of the other tags.

Documentation pages that do include chunks of source show badly on the
page. Even if the code did show nicely on the pages, in most cases, it
does little to enhance the documentation text.

There are a couple of exceptions, like filters, where including the
source helps enhance the text, but examples like that are rare.

The source problem was only one point (out of five) in the report for
that page.