Who are "Administrator" docs for?

📝 Documentation
1

Background & Question:
Deployment docs are currently under the “Administrators” section of documentation, which per this document was for “Person at funding org who is in charge of other Staff” but we also wanted to include documentation related to deployment and configuration of Hypha.

Problem:
I think this section may conflate two roles/purposes (though possibly just in my mind). Here’s how I was seeing it

The original “Administrator” I imagined was someone who:

  • is housed within the funding organization
  • may or may not have a tech background, so needs more plain language documentation
    • secondary to this, does not want/need to see the deployment and configuration docs
  • may be in charge of deciding whether the org uses Hypha, and as such will want access to more meta-level and some (but not a lot of) technical information about Hypha
  • is engaging in “higher-level” tasks within Hypha that need a different level of permissions/access than “Staff” has, which makes me think we would want to separate this documentation from the “Staff” documentation

I think some of my confusion stems from the fact that I’m still not totally clear on how the “Administrator” role in Hypha is different from roles like “Staff Admin” or “Staff” (or two roles I noticed for the first time today–that may be new–“Moderator” and “Editor”). I asked for more clarification about this on Zulip.

Current Actions & Asks:
For now, I have moved the deployment and contribution docs under the “Administrators” section, but I would like folks’ thoughts on:

  • What is the purpose of the “Administrators” doc section? (Put another way, who are “Administrator” docs for?)
  • Do deployment docs belong in this section?
  • Do our current organizations actually have a person (or maybe a few people) who do the things my imagined “Administrator” does?
  • Does doc organization need to change? (e.g., do we need a new, separate section with docs for the person deploying, configuring, and maintaining specific instances of Hypha, or one for the “higher-level” tasks that not all Staff will have the ability to do?)
2

@bernard @eriol @blah @dluong just to get some eyes on this question :slight_smile:

3

What is the purpose of the “Administrators” doc section? (Put another way, who are “Administrator” docs for ?)

I would view these folks as either a technical person inside or outside of a funding org or a non-technical person inside a funding org (this one likely getting ‘stuck’ with the Administration role by virtue of being the initiator of Hypha’s use in their org or ‘The most techy person in the funding org’

Administrators, like Fredrik said in the Zulip chat have access to much more than a ‘staff admin’ on the fundamental irreversible changes to the Hypha deployment for them including dangerous stuff such as deleting ‘page permissions’ etc.

Do deployment docs belong in this section?
Yes - when it’s about ‘setting up’ administrative sections of hypha as the administrator and the deployers might be the same person for an/any amount of time.

Do our current organizations actually have a person (or maybe a few people) who do the things my imagined “Administrator” does?

I think so yes, I imagine Di has these kinds of permissions/role in OTF with support from Fredrik and possibly a combination of Karl and Rosy/Chelsea for ARDC but I’m guessing here. I think the ‘administrator’ is a at present a combined collaborative role between deployers/maintainers and key adopter staff by virtue of the fact that no Adopter currently has ‘in house’ tech teams deploying Hypha and are using contractors. I would hope eventually the administrator would be in the funder org eventually once they understand the technical capabilities.

Does doc organization need to change? (e.g., do we need a new, separate section with docs for the person deploying, configuring, and maintaining specific instances of Hypha, or one for the “higher-level” tasks that not all Staff will have the ability to do?)

I’m confused about what you’re asking here? Docs that are most important for deployers/configurers/maintainers should be accessible to them but I think the real problem is currently (and is often the case with using OSS tools) many different people where different hats so the deployer and maintainer might be the same. You won’t really make docs that are just ‘for one role’ when people play many so I would many as many as possible ‘separate and unique’ and link to other relevant docs e.g.

I’m an adopter performing the ‘Administrative’ role and the ‘Staff Admin’ role. My tech contractor play the ‘Deployer’ ‘Maintainer’ and help me with ‘Administrative’ role when I’m unsure.

This person wants access to Administrator and staff admin information but likely also deployer and maintainer roles so they can know what their tech contractors are doing.

So doc organisation will not be super clear ever given how many use cases there potentially are :frowning: for example Allan at DDP does all these roles and more!

I do however, so this as a technical documentation task with collaboration with you as user documentation person → I think this can go on my list for the new technical documentation persons ‘need to look at’ list.

1 Like