239854 - Add description in documentation for each param from editparams.cgi

Status: RESOLVED WONTFIX

(Bugzilla :: Documentation, defect)

Description

[Bruce Armstrong]

User-Agent:       Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)
Build Identifier: 

Perhaps I'm anal, but I think the section of the Bugzilla Guide that discusses 
Administration should cover more of the parameters that appear on the 
parameters page within Bugzilla.  I've suggested changes so that it covers all 
of them (though I've pretty much just copied over the text from the parameters 
page).

Reproducible: Always
Steps to Reproduce:
1.
2.
3.

Comment 1

[Bruce Armstrong]

Attachment: Changes to administration.xml

Comment 2

[Gervase Markham [:gerv]]

Doesn't having the same information in more than one place just increase the
possibility of things getting out of sync?

Gerv

Comment 3

[Vlad Dascalu]

Attachment: Changes to administration.xml (unified diff)

The same patch in the unified diff (use diff -u to generate those).

Comment 4

[Vlad Dascalu]

Indeed. WONTFIX-ing. The documentation is located in this case on the
editparams.cgi page. If we want updates to that, we should update the code to
display the new information, and not the documentation.

Besides, modular plugin-able params will make soon obsolete the placement of
such descriptions in the docs.

Comment 5

[Bruce Armstrong]

>>Doesn't having the same information in more than one place just increase the
>>possibility of things getting out of sync?

Quite true.  I guess my point is that has already happened.  Perhaps the 
simple list of parameters should simply be removed from the administration 
section.

I think the issue is that it's a bit frustrating to find a parameter 
referenced in the edit params page that isn't well documented, so you turn to 
the Administration section of the Bugzilla Guide expecting to find something 
more, and find that it isn't even referenced at all (though other parameters 
are).

It's also perhaps a bit confusing that some of the parameters are documented, 
but in sections other than Administration.  For example, the LDAP parameters 
are discussed in the Installation section, and the language parameters are 
discussed in the Customization section.  Given that the list of parameters was 
given in the Adminstration section, that's where I ass/u/med that the 
explanation of the parameters would be.

Finally, I'm just not sure how folks reading the documentation would even know 
that this version supports time tracking or user matching, as they are 
referenced anywhere that I can find.

Comment 6

[Vlad Dascalu]

> Perhaps the 
> simple list of parameters should simply be removed from the administration 
> section.

We never had the complete list in the docs. What we're having now (in section
3.1: Bugzilla Configuration) is a list of key parameters. It makes sense to
select a subset of our current params and to tell in the docs to the admins:
look, those are the important ones, and this is what you need to know to get you
started more easily.

That's different from having all of them duplicated in the docs.

> It's also perhaps a bit confusing that some of the parameters are documented, 
> but in sections other than Administration.  For example, the LDAP parameters 
> are discussed in the Installation section, and the language parameters are 
> discussed in the Customization section.

It makes sense to document a param in the most suitable section. For example, it
makes sense to document the quips param in the section dedicated to quips, and
cvs params in the section dedicated to CVS. Maybe they could be cross-linked or
something, but that would be another bug.

> Finally, I'm just not sure how folks reading the documentation would even know 
> that this version supports time tracking or user matching, as they are 
> referenced anywhere that I can find.

If that's the case, then we need to write something for it :-). If you have some
free time, search for bugs dealing with this, and if those aren't already
present, open new ones. Write the doc, attach the patch and let's get it checked
in :-)