491261 - [Inconsistencies] Bugzilla Documentor's Guide web page vs. Documentation web page

Status: NEW

(Bugzilla :: bugzilla.org, defect)

Description

[klonos]

User-Agent:       Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.2a1pre) Gecko/20090502 Minefield/3.6a1pre (.NET CLR 3.5.30729)
Build Identifier: 

The Bugzilla Documentor's Guide web page (http://www.bugzilla.org/docs/documentor.html) mentions in its 'Miscellaneous facts about the Bugzilla Documentation' section:

'We currently maintain separate documentation for 4 different versions of Bugzilla: 2.20.x, 2.22.x, 3.0.x and the current development version (3.1.x at this time).'

..., but the Documentation web page (http://www.bugzilla.org/docs/) lists the following versions:

- the older 2.16.x and 2.18.x versions (not maintained I guess, but kept available to public. So no harm in them being listed there).

- the 2.20.x, 2.22.x and 3.0.x versions are listed, as correctly stated in the Documentor's Guide web page.

- the 3.1.x version mentioned in the Documentor's Guide web page is not listed at all in the Documentation web page.

- the 3.2.x and 3.3.x versions are listed in the Documentation web page, but are not mentioned at all in the Documentor's Guide web page.

- the Documentor's Guide web page states that version 3.1.x is the latest in development, but it is 3.5 that actually is (listed as such in the Documentation web page).

Someone with the proper rights should update the Documentor's Guide web page to reflect status of the Documentation web page. Perhaps there should be a procedure document created for the people updating those pages, that instructs them to also update the Documentor's Guide web page (or ping the people responsible for that or at least file a bug so it can be taken care of). Bottom line is this should be done each time new versions are out or replace others.

Another thought is to automate this. In order to achieve this, a version should have a 'in development' flag or something (somehow), previous versions that are also maintained should carry a 'maintained' flag and older versions not maintained anymore a 'obsolete' or no flag at all. The Documentor's Guide web page could then be scripted to list these versions without any future editing required.

A quick solution to this is to:

a) Simply replace the sections I mention above in the Documentor's Guide web page with a link to the Documentation web page, saying: 'see the list of maintained and in development versions' or something similar.

b) Update the listings in the Documentation web page. The development version is already clearly quoted as such. So, the only thing remaining to be done is that either older versions should have a 'not maintained any more' quote or new versions should have a 'still maintained' quote or similar. If older versions get a quote, still-maintained ones don't need to be quoted and vice versa.

What do you people think about all this?


Reproducible: Always

Steps to Reproduce:
1. Visit the mentioned URLs above and see the sections I am talking about.

Actual Results:  
Different versions are listed/mentioned in the two pages.


Expected Results:  
Updates/changes in the Bugzilla Documentor's Guide web page () should be reflected to the Documentation web page ().

Comment 1

[Frédéric Buclin]

Yeah, we shouldn't mention specific versions at all.

Comment 2

[Liz Henry (:lizzard) (relman/hg->git project)]

Agreed, this seems unlikely to be updated with every release, so the links to documentation for specific versions shouldn't be on documentor.html.