Re: Add Change Badges to documentation

On Fri, Oct 18, 2019 at 07:54:18AM -0400, Corey Huinker wrote:
>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".
>

Looks useful. I sometimes need to look at a command in version X and see
what changed since version Y. Currently I do that by opening both pages
and visually comparing them, so those badges make it easier.

>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).
>

Yep.

>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.
>

Not sure about this. It'd require marking all changes with the badge,
but we'll presumably mark only the large-ish changes, and it's unclear
where the threshold is.

It also does not work when removing a block of text (e.g. when removing
some limitation), although it's true we often add a new para too.

>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.
>

Presumably we could keep the SGML source and only decide which badges to
ignore during build of the docs. That would however require somewhat
more structured approach - now it's a single attribute with free text,
which does not really allow easy filtering. With separate attributes for
new/removed bits, e.g.

<para new_in_revision="11">

and

<para removed_in_revision="13">

the filtering would be much easier. But my experience with SGML is
rather limited, so maybe I'm wrong.

>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.

Haven't looked yet, but I agree the colors might need a change - that's
a rather minor detail, though.

regards

--
Tomas Vondra http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services