Skip to content
This repository has been archived by the owner on Nov 16, 2022. It is now read-only.

Improve IA #154

Closed
wants to merge 5 commits into from
Closed

Improve IA #154

wants to merge 5 commits into from

Conversation

rohitpaulk
Copy link
Contributor

Fixes #146.

Before:
screenshot from 2015-03-11 14 12 42
After:
screenshot from 2015-03-11 14 13 17

@chadwhitacre
Copy link
Contributor

What I'm seeing here is:

Big Picture
General Guides
Developer Guides
Administrator Guides
Appendices

If this were to be hierarchical then I would expect:

Big Picture
Guides
  General
  Developer
  Administrator
Appendices

@chadwhitacre
Copy link
Contributor

By changing "How to" to "Guides" we lose the phrasing "How to ... advocate for users" both in the titles and in the URLs.

@chadwhitacre
Copy link
Contributor

From #146 (comment):

Definitely. I think that every how-to will fall under one of the following groups:

  • Development
  • Design
  • Finance
  • Admin
  • General

I'm not comfortable with the way this hierarchy is (pseudo-)implemented on this PR.

  • System Architecture and Source Code have moved from Big Picture to Developer Guides. They're not Guides because they don't describe a process, they describe a state. The essence of a Guide (did the name How To make this clearer?) is that it is an algorithm for a human to follow.
  • Run a Script is under Developer Guides, but the only page that references it is under Administrative Guides.
  • Why is Deal With Bad Behavior a General Guide, while Handle Terms Violations is an Administrator Guide?
  • Why is Advocate for Users a General Guide, while Support Users is an Administrator Guide?

I think the imposing some order on Guides is a good one, but I don't this PR needs more work.

@chadwhitacre
Copy link
Contributor

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?

@rohitpaulk
Copy link
Contributor Author

By changing "How to" to "Guides" we lose the phrasing "How to ... advocate for users" both in the titles and in the URLs.

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'm not comfortable with the way this hierarchy is (pseudo-)implemented on this PR.

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.

System Architecture and Source Code have moved from Big Picture to Developer Guides. They're not Guides because they don't describe a process, they describe a state. The essence of a Guide (did the name How To make this clearer?) is that it is an algorithm for a human to follow.

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

  • User's guide
    • Getting Started
    • Working with xxx
    • Your confluence
    • Permissions and Restrictions

Many pages in that Guide just describe a state, not a process.

Run a Script is under Developer Guides, but the only page that references it is under Administrative Guides.

Aah yes, that should be changed.

Why is Deal With Bad Behavior a General Guide, while Handle Terms Violations is an Administrator Guide?

The content in "Deal with bad behavior" didn't strike me as only related to administrators, whereas that in "Handle Terms Violations" did.

Why is Advocate for Users a General Guide, while Support Users is an Administrator Guide?

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.

@rohitpaulk
Copy link
Contributor Author

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").

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?

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?

IG is mainly targeted at Staff, isn't it? Worth trying though. Let's see how it'd look -

USERS

CONTRIBUTORS

  • Behave Well
  • Respond to Haters
  • Translate Gratipay
  • Build Gratipay
  • Deal With Bad Behavior
  • Format Source Code
  • Advocate for Users
  • Tell People About Gratipay

OWNERS

STAFF

  • Manage Queues
  • Train New Contributors
  • Review Accounts
  • Run a Script
  • Run MassPay
  • Run Payday
  • Shuffle Escrow
  • Support Users
  • Configure a Bank Account
  • Configure PayPal
  • Onboard Yourself
  • Handle Security Issues
  • Handle Terms Violations
  • Install an SSL Certificate
  • Label GitHub Issues
  • Payout Bitcoin

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.

@chadwhitacre
Copy link
Contributor

How-tos are a list of instructions for people to follow. A guide just provides information, not necessarily a list of steps.

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.

IG is mainly targeted at Staff, isn't it?

Let's get clear on the Users, Contributors, Owners, Staff categorization:

roles

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).

@chadwhitacre
Copy link
Contributor

That's a rough categorization that I could come up with.

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.

I don't like how this places articles targeted to developers and non-developers in the same section.

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:

  • according to skillset
  • according to level of access

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 /howto/ for the rest. How about these:

  • Behave Well
  • Label GitHub Issues (since this is where we define our labels)
  • Manage Queues
  • Onboard Yourself
  • Respond to Haters
  • Tell People About Gratipay

@rohitpaulk
Copy link
Contributor Author

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 /howto/ for the res

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.

@rohitpaulk rohitpaulk closed this Mar 16, 2015
@rohitpaulk rohitpaulk mentioned this pull request Mar 16, 2015
@chadwhitacre chadwhitacre deleted the improve-ia branch September 12, 2015 16:32
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Simplify information architecture of Inside Gratipay
2 participants