-
Notifications
You must be signed in to change notification settings - Fork 38
Conversation
What I'm seeing here is:
If this were to be hierarchical then I would expect:
|
By changing "How to" to "Guides" we lose the phrasing "How to ... advocate for users" both in the titles and in the URLs. |
From #146 (comment):
I'm not comfortable with the way this hierarchy is (pseudo-)implemented on this PR.
I think the imposing some order on Guides is a good one, but I don't this PR needs more work. |
The Development, Design, Finance, Admin, General hierarchy is loosely based on the departments or roles one finds in other organizations, though it leaves out some things like HR ("Deal With Bad Behavior") and Sales ("Tell People About Gratipay"). It occurs to me that instead of these traditional roles as our organizing principle, we could adopt a hierarchy more in keeping with our open company ethos. What if we built on the hierarchy already established in Welcome? That is: Users, Contributors, Owners, Staff. What if we organized the Guides based on the level of access that was needed to carry out each process? |
Hmm, true. How about replacing each section title with an appropriate form such as "Format source code" -> "Formatting source code", "Build Gratipay" -> "Building Gratipay"?
I understand, it is kinda hacky. I'm looking for the least number of changes required to get rid of the loooong how-to list we have. I don't want to make big changes to the UI or change the content of our pages and complicate this - just a small restructuring.
How-tos are a list of instructions for people to follow. A guide just provides information, not necessarily a list of steps. For example, https://confluence.atlassian.com/display/DOC/Confluence+User%27s+Guide
Many pages in that Guide just describe a state, not a process.
Aah yes, that should be changed.
The content in "Deal with bad behavior" didn't strike me as only related to administrators, whereas that in "Handle Terms Violations" did.
The steps in "Supporting users" require access (freshdesk), the ones in "advocating for users" doesn't. I guess there is a bit of ambiguity in who I'm considering as administrator here - I take it as anyone who has access that only a few of our staff do - freshdesk, heroku, balanced etc. |
My line of thought was - when we have 3+ pages for something like Sales, we spin it out to a different section. Until then, it stays in General. Maybe "miscellaneous" would be more appropriate?
IG is mainly targeted at Staff, isn't it? Worth trying though. Let's see how it'd look - USERS CONTRIBUTORS
OWNERS STAFF
That's a rough categorization that I could come up with. I don't like how this places articles targeted to developers and non-developers in the same section. Eventually, when we have design guides and finance guides, it'd get worse. |
Right. We have Big Picture and Appendices for informational pages. The current purpose of How To is to provide lists of steps. I understand wanting to get rid of the long how-to list, but I don't think muddying our top-level distinction is the way to do it.
Let's get clear on the Users, Contributors, Owners, Staff categorization: In my view, IG is targeted at Contributors, including the subset of Contributors that is Staff, and the subset of Contributors that is a partial subset of Owners (Owners is fuzzy right now; once #72 lands it may become the case that Owners is entirely a subset of Contributors). |
Not bad for a start. I would drop Users since IG isn't targeted at them, and Owners because it's a fuzzy category and is properly empty here. Within Staff we have additional degrees of access, which could be used in this hierarchy as well.
Why not? I don't want to overdetermine people according to distinctions such as developer/non-developer. I want to encourage work across disciplines. This could point up the limitation of hierarchies, in that we've now identified two ways to slice these howtos:
This is why I think tagging/filtering will be a better long-term solution. For a short-term fix to the "homepage howto list is too long" problem, I suggest that we pick a half-dozen that apply most broadly, and have a "more" link to
|
That's not fixing the problem, it's hiding it. :P I'm closing this for now - looks like there's no quick fix to this problem, it's got to be tackled with a major structural change :) I'll cherry pick the generic commits and send in a separate PR. |
Fixes #146.
Before:
After: