Re: [gentoo-doc] [RFC] Marking unmaintained documents

[Xavier Neys]

*This is not a double post even though it might look like one, please read on*

Jan Kundrát wrote:
 > Hi GDP-related entities,
 > as promised on IRC, here are my ideas about $SUBJECT.
 >
 > Currently we have quite a lot of "unsupported"/"invalid"/"unmaintained"
 > documents for one of these reasons:
 >
 > a) Third party article
 > b) Older Handbook
 > c) Translation in language which is not officially supported
 > d) Outdated translation


Outdated translations are something different, but more about that later.

Adding a disclaimer at the beginning of a doc is a good idea IMO.

To clear a few points:
Adding a disclaimer is not about about making a doc unofficial.
Everything that we publish is official, or has been so at least.
If we want to make a doc officially unofficial, we remove it.

Of course, users reading a 2004.3 handbook should realise it's old, but they 
could at least be told it's not maintained anymore so that 1) they can read it 
with a grain of salt 2) they should not bother submitting bugs.

Dumping the text in the doc itself is not a great idea as it will lead to 
cut'n'paste errors and lose consistency. Besides, scripts could not 
distinguish normal content from such disclaimers.

Another way would have been to list the outdated/unmaintained docs in an 
external file, or add attributes to metadoc. IMO, this adds some unnecessary 
complexity.

I much prefer something along Flammie's idea, a new tag. This way, we just 
need to add the tag to the relevant doc and forget about it.

As we already see the need for different disclaimers, I suggest using a 
<disclaimer> tag with a type attribute. The relevant text is fished from our 
inserts.xml files and I suggest displaying it right at the top of the content 
area. It needs to be either before, after or on the side, but I'd rather not 
insert it randomly in the text.
It does not need to be red. Text surrounded by a simple dark blue border might 
just do.

I have implemented a proposal with the following disclaimers:
"articles" for republished articles
"oldbook" self-explanatory
"obsolete" idem
Disclaimers can also auto-redirect users, very useful for obsolete docs.

Samples:
http://gentoo.neysx.org/mystuff/gentoo-x86-install.xml
http://gentoo.neysx.org/mystuff/l-sed2.xml
http://gentoo.neysx.org/mystuff/l-sed1.xml
http://gentoo.neysx.org/mystuff/oldbook.xml


Now about outdated translations:
It's possible to use metadoc to check the corresponding original and display a 
note about a more recent original.
I've implemented the following:
If a translation is not listed in its local metadoc, warn users translation is 
not maintained.
If a translation is listed in its local metadoc, but not in the parent one 
(ie. the English one), warn users original doc is not maintained anymore.
If file appears both in local and English metadocs, compare their versions and 
warn users that a more recent original exists with a link to it.

Some doc dev complained that comparing the dates would not work if two updates 
occurred in the same day. True. Comparing the versions is a bit more complex 
and involves two extra scans of the handbooks (the original and the translated 
one). It's fast enough IMO. My <300Mhz test box still delivers handbook 
chapters under the second. Note that it is still not 100% fool-proof. If a 
chapter disappears from the original, the mention of a more recent original 
would not appear on the translations because the xsl scans the original and 
compares the version with the version of the file that is included at the same 
position (part/chapter-wise) in the translation. That has not happened yet.

I'm not going to parse the version strings to try to quantify the amount of 
changes that occurred because 1) versions are not structured 2) a single bump 
could mean a small or a big change, and vice-versa for more bumps. Displaying 
the date of the original should be a good indication.

Notes:
0) All languages must have a metadoc.xml. Not a problem IMO. <metadoc/> will 
do for currently unsupported languages.
1) We have to use metadoc and *may not* test the corresponding file (ie. 
s:/pl/:/en/:) as that would force us to keep files we want to remove in 
/doc/en/ until all translated versions have disappeared.
2) Reminder: the date of a handbook is the max_date(master, all parts)
3) Some of you need to stop bumping dates needlessly because it would make 
translations look older then they actually are.
4) link attributes must contain the full path, no more <book 
link="handbook-x86.xml"> (not required on my test site, but would be on www.g.o)

At the moment, it is limited to /doc as dates are not reliable outside of /doc 
anyway (not yyyy-mm-dd formatted or not bumped properly).

Samples:
http://gentoo.neysx.org/doc/fr/handbook/2005.1/handbook-amd64.xml?part=1&chap=2
http://gentoo.neysx.org/doc/pl/nvidia-guide.xml

FYI, an inserts would like like
http://gentoo.neysx.org/doc/en/inserts-en.xml?passthru=1

Please comment.


Cheers,
-- 
/  Xavier Neys
\_ Gentoo Documentation Project
/  French & Internationalisation Lead
\  http://www.gentoo.org/doc/en
/\


-- 
gentoo-doc@g.o mailing list