Thread: 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

Hello Corey,

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

More precisely, it is a POC to show that the infra works. It adds 3 badges 
on various entries.

Patch applies cleanly, compiles, and indeed (too) green boxes show up. 
Good.

Maybe it would be better with badges at the end of lines, otherwise it 
interferes with the proper alignment of text. Also, ISTM that the shorter 
the badge contents the better, so "v13" is better than "new in version 
13".

Maybe it would be nice to have a on/off CSS/JS controled feature, so that 
they can be hidden easily?

I'm wondering about the maintainability of the feature if badges need to 
be updated, but if this is only "v13" to say that a feature appears in 
v13, probably it is okay, there is no need to update.

However, if a feature is changed, should we start accumulating badges?

Updating the documentation would be a great pain. Maybe it could be partly 
automated.


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

Ok.

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

Possibly. If the maintainer thought about it.

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

Which suggests links to do that?

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

Hmmm, I do not think that we want to add and remove NEW badges on every 
version, that would be too troublesome. ISTM that maybe we can add "v13" 
and have some JS/CSS which says that it is new when looking at v13.

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

Idem, maintainability? Unless this is automated.

> 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

Hmmm.

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

Hmmm.

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

-- 
Fabien Coelho - CRI, MINES ParisTech

On Thu, Nov 07, 2019 at 12:08:43PM +0100, Fabien COELHO wrote:
> More precisely, it is a POC to show that the infra works. It adds 3 badges
> on various entries.

If the final patch could at least finish with one applied, that would
be nice as a base example.  There are no objections for this patch,
but no updates have been provided, so I have switched the entry as
returned with feedback.
--
Michael