[dev] Hiding help entries

[Eric Jon Rostetter]

Quoting Jan Schneider <jan at horde.org>:

>> I'd feel better doing this for configuration items than I would for
>> preferences.  Something disabled in the configuration is much easier
>> to test for and detect reliably.
>
> Not really, it's even easier to test for locked preferences, because
> all pref help entries follow a certain naming theme that could easily
> be used to test whether a preference is locked or not.

Yes, but as I said, just because it is locked doesn't mean it is disabled
or that the user doesn't want to know about it.

But configuration entries are pretty well defined by nature.

> Prefs help entries usually don't document a feature, but help the user
> to decide how he wants to set the preference. If he doesn't have the
> choice, he doesn't need this help.

Are we talking about help entries in the Options pages, or generic help
pages in the various apps that just happen to mention something controlled
by a preference?

> Admins shouldn't depend on the online user help to make decisions
> about preferences or configuration items.

That is true, but this isn't a perfect world.  I'll ceed to your
point though really, as it isn't proper even if it is too often done.

> No, but it means that it doesn't make sense to show a help for it. The
> user doesn't get to the help entry because he doesn't even see the
> preference. He would only get to it from the help index, and then he
> wonders what it's all about, because he never sees the preference.

If we are talking only about the help for the Options page, then I
agree.  I assumed we were talking about all help menus, not just that
for the Options page.  I need clarification I guess on what is being
considered here.

>> To hide based solely on the locked state is bound to cause documentation
>> loss.
>
> Or to avoid confusion.

Depends on which help files we're talking about.

>> And last, should we not implement this for configuration as well as
>> preferences?
>
> Yes, maybe, but it's much easier for preferences.

But once again, just because it is easier doesn't mean it is correct.
If we should do it for both, then we should either do it for both,
or do it for the easier one and put the other on the to-do list (or
even offer a bounty, etc).

> Jan.

The now confused as to what we are talking about Eric. ;)

-- 
Eric Rostetter
The Department of Physics
The University of Texas at Austin

Go Longhorns!