[dev] Hiding help entries

[Jan Schneider]

Zitat von Eric Jon Rostetter <eric.rostetter at physics.utexas.edu>:

> Quoting Oliver Kuhl <okuhl at netcologne.de>:
>
>> I'm currently reviewing the german help for several modules and have
>> to remove parts which are disabled in the prefs in our configuration.
>> Searching the mail archives I found an old thread about this:
>> http://thread.gmane.org/gmane.comp.horde.devel/6187/
>
> One could make an argument that help files and documentation files should
> include all the docs, even if the site can disable them.  Of course,
> I completely understand the opposite argument also.
>
> 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.

>> If I didn't miss anything, nothing regarding this is implemented right
>> now. What do people think about this? To summarize: It would be nice
>> to hide *locked* or otherwise completely disabled functionality
>> automatically.
>
> What if I lock a preference not to disable it, but to enable it in
> a fixed way?  I don't want to remove the documentation (help) since
> the feature is still available.  We'd need to check for things which
> can be locked in a disabled state, versus locked in an enabled state.

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.

>> In my case, I have to manually remove only the parts in the german
>> help files. But people supporting multiple languages need much time
>> for this.
>
> Is it really that important that it be removed.  An alternative could be
> simply testing for locked state and annotating the entry rather than removing
> it.  I bet there are other options too... Maybe we hide it from "non-admin"
> users but for admin users we annotate it with the information that it is
> disabled, and how to enable it?

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

>> The performance overhead should be ok due to few usage of the help   
>>   in general.
>>
>> So is there anything planed regarding this one?
>
> I don't know of anything, but I would say it really needs some thought
> to do right.  Just because it is locked doesn't mean it is disabled.

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.

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

Or to avoid confusion.

> There's also the idea of if something is disabled and not locked, should
> we tell them how to enable it, and so on.

No, admins lock prefs, not users. User don't need to know about  
software administration.

> And last, should we not implement this for configuration as well as
> preferences?

Yes, maybe, but it's much easier for preferences.

Jan.

-- 
Do you need professional PHP or Horde consulting?
http://horde.org/consulting/