Re: Add Change Badges to documentation - Mailing list pgsql-hackers

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