Feature Proposal: Centralize and hide administrative instructions

Motivation

There are a number of notes to TWiki administrators giving details of things that should be done post-installation which currently are distributed all over the place. Two examples are the message at the bottom of the TWikiRegistration page and the note at bottom of TWikiAdminGroup. There are probably others that I'm forgetting right now or haven't stumbled across.

A undocumented step of setting up a new installation is to go around and remove all of these.

I think there is a better way to treat these messages.

Description and Documentation

What I propose is to:

• Create a topic in the TWiki web called something like TWikiAdminInstructionMessages and put all of these message in named sections within this topic. Set ALLOWTOPICVIEW for this topic to TWikiAdminGroup.
• Remove these messages from their current locations and replace them with a INCLUDE tag referencing this new topic with the appropriate section reference. Include warm="off" so that non-TWikiAdminGroup user don't see the message saying they don't have permission to view the INCLUDED text.

In this way, members of TWikiAdminGroup will see the messages they need to see but no one else will, thereby removing the need for "cleaning up" all these instructions.

A bit fancier enhancement would be to create a CommentPlugin template that provides a button that simply removes the INCLUDE tag. So the admin person would see the message followed by a button that says "OK, I've done this" and when they click it, the instruction message disappears. I've designed a comment template like this and it works nicely.

Examples

Impact

WhatDoesItAffect:

Documentation, Refactoring, Usability %WHATDOESITAFFECT%

edit

Implementation

-- Contributors: LynnwoodBrown - 01 Nov 2007

Discussion

Sounds good. I really like the idea of not showing these infos to normal users.

-- CarloSchulz - 02 Nov 2007

Go for it. MAIN is your playground.

-- CrawfordCurrie - 02 Nov 2007

Good idea.

One detail: Some messages need to be shown even before authentication is working, such as the one in Main.TWikiAdminGroup. For those special cases it would not make sense to do the hidden INCLUDE.

-- PeterThoeny - 02 Jan 2008

The TWikiAdminGroup one (for eg) could be done conditional on the GROUP being set, or, a combination of similar.

-- SvenDowideit - 02 Jan 2008

The message in TWikiAdminGroup is not really an issue. There is no reason to hide it for anyone. It is not part of the common user interface in any way. On the contrary for the admin that has forgotten how to use the temporary admin login this info is quite helpful. I would hate if we suddenly start hiding this. You are not an admin when you need this info but you desire to become one. TWikiAdminGroup is not a topic a normal user will ever need to land on as part of his normal use of TWiki. It does not disturb anyone that there is some instruction on this one topic.

The registration page no longer has any messages you need to remove so I think Lynnwood may base this proposal on how TWiki used to be and not how it looks in the 4.2.0 we are about to release.

The problem in the past have been those yellow messages that were spread all over the place on common user interface pages like the registration page, change password page, reset password page etc etc.

But I think there are very few of these left. Sven and others have been really good at replacing the yellow boxes with conditional text so that the admin does not normally need to change anything.

Only in the cases of not using any password manager do you have to maybe alter reset and change password pages with a message to where to so this centrally and here it is always different from company to company.

But when here we could make the entire message conditional and replace the content by the content of two TWiki variables CHANGEPASSWORDMESSAGE and RESETPASSWORDMESSAGE which could be defined in Main.TWikiPreferences. If defined this short message would be displayed instead of the normal reset and change application. Normally all you will need is a one liner saying.

"To reset the password please go to corporate single sign on password management site at http://password.company.com"

This way the admin can add these two variables to TWikiPreferences and not worry about this anymore when upgrading.

If these variables are not defined and the password manager is none, the reset password and change password topics can give a generic message that says "Passwords are not managed by TWiki, please contact your system administrator".

Where else do we have any such instructions that need to be hidden?

-- KennethLavrsen - 02 Jan 2008

I changed date of commitment to the day Sven added the date. The application that lists the new proposals where the 14-day rule applies does not show proposals without a date so I had not noticed this one. You cannot add a date in the past and suddenly a proposal very few have seen is auto accepted. We need a change to read the new proposals and raise concern in a 14 day period. That is the whole idea of the process. And in this case I have concern about hiding user interface for the admin that has forgotten how to use the "sudo".

-- KennethLavrsen - 02 Jan 2008

Lynnwood, can you respond please?

-- KennethLavrsen - 30 Mar 2008

Am thinking Lynnwood meant in a root vs administrator scenario. Where installation notes for admins (root) should only be available for the admin, or TWikiAdminGroup, for the initial stages, whilst anything else can be done via SudoGroup (administrators).

If that's true, I agree with Lynnwood.

-- KwangErnLiew - 31 Mar 2008

My apologies for not tracking this proposal better. After seeing that some of these comments were removed in 4.2, I concluded that it had been addressed. However, reviewing this topic now and going back an looking for incidences of messages targeted to TWikiAdminGroup, I think this approach still has merit. In fact, I think that it would be worth considering increasing the use of admin help and tips, but keep them hidden by using the method I proposed originally here.

In the case of TWikiRegistration, I think that the message targeted to TWikiAdminGroup was important because it's quite likely that they would customize the registration page and equally likely that they would not remember to modify the related files. So I don't think it would have been a preferable solution to hide this comment than simply drop it altogether.

In the case of TWikiAdminGroup, Sven's use of a conditional does do the job there and perhaps that is the best solution for that particular case because of the unique situation where that information is only relevant prior to defining membership in TWikiAdminGroup. However, I propose that there is a down side to using these conditional statement to hide admin help messages. That is that it leaves these messages scattered around with no simple way to find them all. Under my original proposal, all of these admin messages would be consolidated within a single topic so that they reviewed (and followed up on or updated) from a central location.

If we implemented this simple framework, I would suggest that it might be useful to expand use of these hidden administrative tips and suggestions. Just a few examples of where messages to admin users might be added and/or hidden:

• In WebNotify, the message at the end about what is required to enable notification could be hidden, except to the admin user.
• In WebStatistics, the notes at the bottom of the page about enabling and archiving statistics.
• In ResetPassword and ChangePassword, put back in the messages about changing the message is using a different user management setup.
• In TWikiUsers, hide the message at the bottom about the special system users.
• In WebPreferences, display some additional information about setting access control on the web level. This is critical essential admin information that I've found that admins don't remember because they don't do it often. The help text could be enclosed in a twisty so as not to take up much screen space but is readily available.
• In TWikiAdminUser the information about "How to login as TWikiAdminUser" and somewhat sensitive information about resetting the admin password.

In summary, I think it would be useful to provide more in-context hints and additional information to TWikiAdminGroup but at the same time reduce the exposure of these messages to regular users. Furthermore, having all the messages centralized into one topic within the TWiki web would provide a central reference for all the post-installation actions and options that TWikiAdminGroup might want to follow up on.

If this scenario makes sense to folks, I'm still willing to implement it. I'd set up the basic infrastructure and implement it for some of the topics i've listed above.

-- LynnwoodBrown - 15 Apr 2008

I've subscribed to this topic now so as not to miss further discussion.

-- LynnwoodBrown - 15 Apr 2008

I see 2 scenarios

1. Hiding information only needed by an admin.
2. Hiding information from a person is is supposed to be an admin but is not.

WebNotify could need a good simplification. Most of the information tells the user how he can add himself to the Notify list. When the user has read and understood this he should ask his manager for a raise. He will be Doctor WebNotify. Hiding is not the solution. Simplify would be better. There is ONE line of admin note on the topic. Not worth hiding.

WebStatistics is a story by itself. I as an admin never update it. My users however do often. This feature is strange and needs a tender loving care instead of hiding.

TWikiUsers - I do not see who we protect from hiding one line of text about the special system users.

WebPreferences - If you can improve the text to aid the admin or the web master (this topic is not a real admin page - I assign a web master for each web who does not belong to the TWikiAdminGroup but has edit rights to WebPreferences) then go ahead. No feature request approval needed to improve documentation. Just go ahead Lynnwood.

TWikiAdminUser. Again you cannot hide. The admin user that has forgotten his password or goofed up his password needs this info at a time where he is NOT admin.

-- KennethLavrsen - 15 Apr 2008

You're probably right Kenneth regarding those cases of one or two-line notes to administrators. You didn't comment on the case of TWikiRegistration where I think there is good reason to have a note to administrators about what they need to do if they modify the form. But if this is the only such case, then perhaps using the conditional display is the best course....

-- LynnwoodBrown - 16 Apr 2008

Sorry for missing your reply and taking so long to reply.

Yes. Today there is no longer any admin note on the TWikiRegistration form and for sure if we add any it should be hidden to the normal user.

This would be a docu update that does not need proposal decision and you are even welcome to do it on the 4.2.1 branch if you wish to.

But maybe it is not worth it.

One of the last annoyances when upgrading is that when you upgrade the TWikiRegistration topic gets overwritten. I personally have this customized to match some fields in my customized userform so this is one of the topics I have saved in a special directory so I caqn restore it again after an upgrade. Probably one of those where a copy in Main web should override the default in TWiki web. And then with this some better installation doccu. For TWiki 5.0 the entire installation doc will be one of my todos.

I am removing my concern now. If you want to improve the doccu already now go ahead.

I am turning this to accepted by consensus and changing the headline to match the conclusion.

-- KennethLavrsen - 29 May 2008

I too would like to have a better way to customize the UserRegistration topic. Or, for it to be removed/replaced when registration isn't relevant.

-- SvenDowideit - 14 Feb 2009

Reviewing this proposal after loooong delay and concluded that it has substantially been addressed in current design of UserRegistration, AdminGroup and other topics referenced. Therefore, I'm setting the current state as "Discarded Proposal" since it's no longer relevant.

-- LynnwoodBrown - 03 Dec 2015

Commenting is disabled while not logged in