Add Change Badges to documentation

From: Corey Huinker <corey(dot)huinker(at)gmail(dot)com>
To: pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Add Change Badges to documentation
Date: 2019-10-18 11:54:18
Message-ID: CADkLM=cLdmvLxGncbzs7J-xe6jhp6cvXmruR+eOPZGK5JJhxEQ@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Attached is a patch to implement change badges in our documentation.

What's a change badge? It's my term for a visual cue in the documentation
used to indicate that the nearby section of documentation is new in this
version or otherwise changed from the previous version.

One example of change badges being used is in the DocBook documentation
reference:
https://tdg.docbook.org/tdg/4.5/ref-elements.html#common.attributes

Docbook used graphical badges, which seemed to be a bad idea. Instead, I
went with a decorated text span like one finds in gmail labels or Reddit
"flair".

The badges are implemented via using the "revision" attribute available on
all docbook tags. All one needs to do to indicate a change is to change one
tag, and add a revision attribute. For example:

<varlistentry revision="new in 13">

will add a small green text box with the tex "new in 13" immediately
preceding the rendered elements. I have attached a screenshot
(badges_in_acronyms.png) of an example of this from my browser viewing
changes to the acronyms.html file. This obviously lacks the polish of
viewing the page on a full website, but it does give you an idea of the
flexibility of the change badge, and where badge placement is (and is not)
a good idea.

What are the benefits of using this?

I think the benefits are as follows:

1. It shows a casual user what pieces are new on that page (new functions,
new keywords, new command options, etc).

2. It also works in the negative: a user can quickly skim a page, and
lacking any badges, feel confident that everything there works in the way
that it did in version N-1.

3. It also acts as a subtle cue for the user to click on the previous
version to see what it used to look like, confident that there *will* be a
difference on the previous version.

How would we implement this?

1. All new documentation pages would get a "NEW" badge in their title.

2. New function definitions, new command options, etc would get a "NEW"
badge as visually close to the change as is practical.

3. Changes to existing functions, options, etc. would get a badge of
"UPDATED"

4. At major release time, we could do one of two things:

4a. We could keep the NEW/UPDATED badges in the fixed release version, and
then completely remove them from the master, because for version N+1, they
won't be new anymore. This can be accomplished with an XSL transform
looking for any tag with the "revision" attribute

4b. We could code in the version number at release time, and leave it in
place. So in version 14 you could find both "v13" and "v14" badges, and in
version 15 you could find badges for 15, 14, and 13. At some point (say
v17), we start retiring the v13 badges, and in v18 we'd retire the v14
badges, and so on, to keep the clutter to a minimum.

Back to the patch:
I implemented this only for html output, and the colors I chose are very
off-brand for postgres, so that will have to change. There's probably some
spacing/padding issues I haven't thought of. Please try it out, make some
modifications to existing document pages to see how badges would work in
those contexts.

Attachment Content-Type Size
0001-add-document-change-badges.patch application/x-patch 2.4 KB
badges_in_acronyms.png image/png 89.2 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Lars Kanis 2019-10-18 12:01:23 Re: libpq: Fix wrong connection status on invalid "connect_timeout"
Previous Message Dilip Kumar 2019-10-18 11:21:14 Re: Questions/Observations related to Gist vacuum