Skip to content

user management procedures are poorly documented

as identified by @arma in #40126 (comment 2721379), it's not really clear how to actually create and remove accounts. we do have #32519 (closed) which concerns the overall onboarding/offboarding process, but the actually nitty-gritty details of how to do things for sysadmins is really badly documented. in #40126 (comment 2721468), i noted:

This documentation seems to be a total mess. There is:

  • howto/new-person which you have found and seems to document how to get a new sysadmin on board
  • doc/accounts which documents "accounts" in general, and is more targeted at users
  • howto/create-a-new-user actually documents how to create a new user
  • howto/ldap which documents "LDAP" in general and has a rather poor user-facing documentation and is mostly targeted about running the service
  • and then of course userdir-ldap-cgi has its own inline documentation maintained as HTML/Perl templates shipped with the debian package and managed through git.

Someone(tm) needs to sit down and make sense of this. I kind of made matters worse myself by creating howto/ldap and howto/new-person of course... :( so I guess i'm probably that someone.

So the task here is to merge or split or cleanup those pages so that one doesn't get lost like @arma did. Here it's not a matter of policy, it's just about creating a cohesive documentation. I suspect the following should happen, but this is just a first brainstorm and i'm open to suggestions:

  • howto/new-person - should be merged into another page, a special section in create-new-user maybe? or renamed to "new-admin"?
  • doc/accounts - merge with create-a-new-user?
  • howto/create-a-new-user - merge with howto/ldap? but keep in mind there are things about sudo in there
  • howto/ldap - should this take over the userdir-ldap-cgi documentation below and cover everything?
  • userdir-ldap-cgi has its own inline documentation - maybe deprecate this and point to the wiki?

There's also broader onboarding problems in the larger community, see those documents for example:

TBD.

Also note that our retirement procedures are also fairly inadequate and would need much love. this was supposed to be covered by #32519 (closed) but was somehow overlooked... :(

Edited by anarcat