I guess I'll never know what I did wrong. Thanks for your time.

You've read that documentation and this request represents a sincere effort to follow the instructions it contains?

In fact, I did read it. I believe I've effectively described the problem. I can't believe that nobody else has this problem nor that the intent of my feature request is unintelligible. Would a more compliant description be: There is no way to add a user to more than one project at a time. Visiting each of 30 projects individually is a waste of time. Or even, more generally, modifying a user's settings for global things like project membership is impossible without visiting each project individually.

The request doesn't state a core problem, which is required on all feature requests. A core problem is the why of the feature request. See Describing Root Problems if you need a bit more help understanding what we're looking for. We already have thousands of other feature requests, so if you tell us what you're trying to do and why, there may already be another task or another means to accomplish what you want.

I'm going to ask you a series of questions to figure out what your actual root problem is. When we're done, I'd like you to explain why you didn't just describe it in the first place after reading Describing Root Problems, and how we could improve that document so that you would have gone through this process on your own, umprompted, without requiring me to spend time asking you questions instead of improving Phabricator.

Let's start with "5 Whys", a technique described in Describing Root Problems:

Visiting each of 30 projects individually is a waste of time.

Why do you need to add users to 30 projects at once?

In this case, we have a new developer and he needs to be added to multiple projects.

In this case, we have a new developer and he needs to be added to multiple projects.

Why do new developers need to be added to multiple projects?

They will be working on multiple projects.

They will be working on multiple projects.

Why do developers need to be members of the projects they are working on?

Why shouldn't a developer be a member of a project they are working on? Even if a project is used as a security group for use in the Visible To or Editable By fields in a task or project there might be multiple security groups they need membership to.

Why shouldn't a developer be a member of a project they are working on?

Well, for one, it sounds like it takes a lot of time to add them to all those projects. Why do this work if there isn't a real reason for it?

Even if a project is used as a security group for use in the Visible To or Editable By fields in a task or project there might be multiple security groups they need membership to.

Are these projects actually used as security groups? Do you have 30 projects with mutually exclusive security policies, so that members of one project are not allowed to see (or edit, or whatever else) information in other projects?

Well, it sounds like what you're getting at is that we're using Phabricator incorrectly.

There aren't 30 security groups, there are probably closer to 10. We do a lot of work with other companies. Each company has its own security group. They are mutually exclusive (a project that is for company A is only ever visible to users from that company and us and never company B). Our internal developers need to be members of all (or a subset) of them. Adding our developers to each of those groups on a project by project basis is a waste of time.

How common is it that a developer is only allowed to see company A, and not see company B? Is this common, or can most employees see all or almost all of the information about companies and you mostly want to prevent employees of company A from seeing information about company B and vice versa?

How do you currently know which 30 projects to add new developers to?

When a new company becomes a client, do you create a project for that company and add every employee to the project?

Do you use Spaces? If so, how? If not, were you aware they exist? If so, why did you decide not to use them?

In T11597#193619, @epriestley wrote:

How common is it that a developer is only allowed to see company A, and not see company B? Is this common, or can most employees see all or almost all of the information about companies and you mostly want to prevent employees of company A from seeing information about company B and vice versa?

The first scenario arises anytime we onboard a new company. If a new internal employee is added a similar issue occurs where we have to add that user to both internal groups and external groups. The real concern is to keep members of company A from seeing tasks and projects for company B.

How do you currently know which 30 projects to add new developers to?

In point of fact, every internal developer needs access to every external company's security group. We have some internal security groups that are used to segregate things like QA from development but the real concern is external groups.

When a new company becomes a client, do you create a project for that company and add every employee to the project?

Essentially, yes.

Do you use Spaces? If so, how? If not, were you aware they exist? If so, why did you decide not to use them?

We aren't using Spaces. I wasn't aware of it until you linked me to it. My colleagues may be aware of it. I guess that's my solution.

I really did read the document and I really wasn't trying to be difficult. I appreciate the time you spent leading me to the solution. Thanks.

Here's roughly the request we would have liked to see instead of the request you actually filed:

We're a company that has other companies as customers, but don't want customers to see one one another's data. Currently, we manage this by creating a new project for each company and setting policies like "Visible To: Members of Customer A" on all of that customer's tasks and other objects. However, this is particularly tedious to manage when we hire a new employee, since they need to be added to every active project ("Customer A", "Customer B", ..., "Customer Z") and there's no UI that allows these changes to be made in bulk. Is there a better way to manage this?

This request provides context and has enough information that I could have pointed you at Spaces immediately, instead of spending time digging. This request would have taken you 5-10 more minutes to write, but you would have received an answer in about 30 minutes instead of more than 2 hours and cost us about a minute instead of about an hour.

Here's how we're expecting users to arrive at requests like that, which include context. First, they're pointed at the Describing Root Problems document on the New Feature Request form and in the Contributing Feature Requests documentation:

The Describing Root Problems document tries extremely hard to convey how important context is, and how to arrive at that context:

Good problem descriptions let us answer your questions quickly and correctly, and suggest workarounds or alternate ways to accomplish what you want.

This request was too specific, and didn't have the context to let us suggest another approach.

Poor problem descriptions require us to ask multiple clarifying questions and do not give us enough information to suggest alternate solutions or workarounds. We need to keep going back and forth to understand the problem you're really facing, which means it will take a long time to get the answer you want.

This is exactly what happened. The rest of the document underscores this and provides many examples of good and bad descriptions:

We want a description of your overarching goal. The problem you started trying to solve first, long before you decided what feature you needed.

Problem descriptions should include context and explain why you're encountering a problem and why it's important for you to resolve it.

Here are some examples of good ways to start a problem description:
My company does contracting work for government agencies...

How could we improve this workflow or documentation to help users arrive at this sort of problem description with appropriate context? What about the documentation wasn't clear? In your case, why didn't you provide this kind of context?

In your own work, do customers simply ask you for things without any context? Do you just implement whatever they ask for without trying to understand why they want it? In your experience, is this how software development normally works -- customers ask for features, and they're implemented verbatim with no planning or requirements gathering phases?

Frankly, my biggest issue when people submit feature requests is all the chaff. But I see how you could want what you're after as far as requests go. I will admit that while I did read the first document and totally missed the second document on root problem description. Given its location in a giant red box, I'm not sure how that happened. I'm sorry for wasting your time.

Even if you don't make it to Describing Root Problems and miss the huge red header in Contributing Feature Requests, that document has a large amount of text with the same message:

You claimed earlier that you'd read the document and made a sincere effort to follow the instructions it contains. Was that not actually true (for example, because you felt like you knew how to file a feature request and I was wasting your time by asking you to read the document and that you'd get an answer faster by just claiming you'd read it)? Or did you miss all the links, the huge red header, the summary, and approximately 30% of the text in the document?

I suppose I could have read it more carefully but at this point I feel like your goal is to make sure I feel bad about it. Again, I'm sorry for wasting your time.

My goal is to fix this process so that we don't have to go through it over and over and over again.

The repeated callouts, giant text, etc., are because many, many users do not follow these instructions and we receive many feature requests like this: approximately one line of text asking for a very specific feature, which wastes our time (and the reporter's time!) and suggests that the author did not read any of the documents. This is worse for everyone than if we could get users to just read the documents -- we'd spend way less time on requests and users would get answers faster. Users who file reports like this are hurting the project and hurting themselves.

When we ask how we could fix things, no one claims they had a hard time finding the instructions. Everyone claims they read them and understood them, and everyone says they are clear after the fact. But I still waste a ton of time asking questions to figure out the root problem, essentially following the techniques and discussion already laid out in the documents, and no one has any feedback to improve the process.

One possible explanation is that a significant number of our users are basically lazy jerks who don't respect our time and are possibly even willing to lie about reading documentation to get a worse answer more slowly than if they'd followed the instructions. I don't like this explanation and I'd like to believe we just did a bad job with some of the documentation, but this scenario has played out so many times now without anyone being able to point at what we should improve that I'm having trouble coming up with other explanations.

The current state of affairs is also extremely negative for everyone. It's really frustrating for us, since it wastes a tremendous amount of our time. It's frustrating for users -- when I pointed you at the documentation, it seems like you felt like I'd just dismissed your problem. But we also can't spend two hours doing this kind of question-and-answer walkthrough with every user. We don't have the resources, and "free help with any question no matter how vague and time consuming" isn't a sustainable model.

My company uses Spaces for external companies and it's painless to manage permissions in that manner.

I have:

• phab project with members who are workers in our company
• phab project with members who are external company A
• phab project with members who are external company B
• etc

Ext. Company A and Ext. Company B are not allowed to see each other stuff, but my company sees all.

On Spaces app, you set "can view" policy to whatever you wish and control stuff from there (example for ext company A is "Can View" to members of project "my company" and "ext company a" . Every member we approve in our instance basically goes to one user group, (maybe 2,3 more for some other purposes but those groups are join-able by users themselves ie. they can join if they wish or are instructed to join if they start to work on some project later at different time) which is not so much of a pain.

The only "pain" is to setup a new company which consists of:

• creating a new space
• creating an new project for members of that company
• creating appropriate policies on space level (can view to our company and new company)
• adding company domain to the auth whitelist which enables them to register
• creating custom forms for Maniphest (company x feature request (each company is given a specific default attributes, different account managers, are redirected to different backlogs, etc)

I wish I could template all of these steps (some are even template-able, like importing workboards from projects) but I feel it's way to custom for our installation that it makes sense for a feature request to phab guys that would ease that flow a bit. I do it all in 5 mins time, and new company setup is not that common (cca every two months),

Kudos to @epriestley and @chad for consistency and patience in explaining how to write feature requests for 1000th time.

In T11597#193651, @epriestley wrote:

My goal is to fix this process so that we don't have to go through it over and over and over again.

The repeated callouts, giant text, etc., are because many, many users do not follow these instructions and we receive many feature requests like this: approximately one line of text asking for a very specific feature, which wastes our time (and the reporter's time!) and suggests that the author did not read any of the documents. This is worse for everyone than if we could get users to just read the documents -- we'd spend way less time on requests and users would get answers faster. Users who file reports like this are hurting the project and hurting themselves.

When we ask how we could fix things, no one claims they had a hard time finding the instructions. Everyone claims they read them and understood them, and everyone says they are clear after the fact. But I still waste a ton of time asking questions to figure out the root problem, essentially following the techniques and discussion already laid out in the documents, and no one has any feedback to improve the process.

One possible explanation is that a significant number of our users are basically lazy jerks who don't respect our time and are possibly even willing to lie about reading documentation to get a worse answer more slowly than if they'd followed the instructions. I don't like this explanation and I'd like to believe we just did a bad job with some of the documentation, but this scenario has played out so many times now without anyone being able to point at what we should improve that I'm having trouble coming up with other explanations.

The current state of affairs is also extremely negative for everyone. It's really frustrating for us, since it wastes a tremendous amount of our time. It's frustrating for users -- when I pointed you at the documentation, it seems like you felt like I'd just dismissed your problem. But we also can't spend two hours doing this kind of question-and-answer walkthrough with every user. We don't have the resources, and "free help with any question no matter how vague and time consuming" isn't a sustainable model.

Fair enough. I would guess that most users aren't intentionally being jerks. I must say being presented with what amounts to a wall of text of instructions is a bit annoying. I see the need you're trying to satisfy but having that much for people to read is likely going to result in a lot of people skimming (like I did the first two times). In short, see if you can boil those instructions down to something a bit more easily consumed. It may be as simple as giving the same request the wrong way and the right way. Having now read the two documents more closely, I can see how that was described. However, if you put forth an example scenario and then literally said

A bad description of this scenario looks like X and a good description of this scenario looks like Y. Please describe problems so that they look like Y.

people would probably be less likely to get confused or annoyed with having to read what amounts to quite a bit. Bluntly, people will always do the apparently easier option and make it your problem unless you make it easier to understand why the harder option is better. It's a lot easier (in the short term) to submit a bad request and get on with your day than read all that.

Thank you for the input, I think we still have room to improve things on our side, like you say - wall of text.

We've iterated through a few versions of instruction lengths without much luck, and an older version of the form had a bit more text upfront but didn't seem to have any impact.

The most extreme version of this is documented in T11095, where a short-lived form only said "it costs $1,500 to submit this form" and the very first person to submit it didn't read that. See T11095#178732 for what that user saw and the task as a whole for what came of it. It's hard to imagine we could make the "root problems" documentation more concise than "Support requests are billed at $1,500/hr."

In T11597#193660, @epriestley wrote:

We've iterated through a few versions of instruction lengths without much luck, and an older version of the form had a bit more text upfront but didn't seem to have any impact.

The most extreme version of this is documented in T11095, where a short-lived form only said "it costs $1,500 to submit this form" and the very first person to submit it didn't read that. See T11095#178732 for what that user saw and the task as a whole for what came of it. It's hard to imagine we could make the "root problems" documentation more concise than "Support requests are billed at $1,500/hr."

Frankly, he probably thought it was a joke. Regarding length and content, I was being literal when I described what I thought might be effective. People want to be told what to do and how to do it even if they say otherwise. Dumb obvious instructions are better than overly complex instructions. You can always keep the longer and more detailed instructions around as well but put the simple instructions at the top.

Also, as an aside, I have to apologize more directly to you @epriestley. I read a lot of things (dismissal) into your initial comments that simply aren't there. Mea culpa. It may be effective to be a little more descriptive about why the submission is invalid (in my case, I described what I was actually trying to do poorly).

To this use case more broadly, Spaces is the best tool we have today but may not be a perfect solution. From elsewhere, here's general thinking on this today (this was originally a response to a request about T8442):

I think we see a range of use cases from more-privileged to less-privileged users, that roughly look like this:

1. Employees - Normal employees who can know that everything exists and have access to most or all of it.
2. Contractors / Open Source Contributors - Like employees, but with a bit less access.
3. Clients / Partners - They should mostly only know about their own stuff, not about other clients.
4. End Users / Customers - No internal access.

Phabricator does a good job with employee-like users (bucket 1) by default since that's the primary audience, and I think it does a reasonable job with contractor-like users (bucket 2) through Spaces.

I think you're running into stuff in bucket 3. I'll come back to that in a moment.

Today, Phabricator doesn't do a very good job with arbitrary end users (bucket 4), which is use cases like user support / helpdesk / ticketing. But these users also probably shouldn't have accounts in Phabricator (a common use case is being able to email "[email protected]", for example, and it's good for users to be able to do that without needing to sign up for an account) or access to applications like Maniphest or Differential. We plan to build a new application ("Nuance", https://secure.phabricator.com/T8783) to handle these use cases (this application sort of exists today, although it doesn't do much of use yet). Once Nuance is built, I expect we'll do a good job with these use cases.

Between buckets 2 and 4 there's a set of "client/partner" use cases where the users should have some amount of access, but information should ideally be completely hidden from other clients. Phabricator isn't really built for this. You can make it work reasonably well, but overall I'd say it doesn't do a great job with it today. Some of these limitations are fixable (for example, as you suggest, making Spaces easier to manage would help with this, and building some kind of Space switching UI would help make Spaces easier to manage) but some of these limitations aren't really fixable (for example, I don't anticipate ever hiding user accounts from other users, or putting Projects into Spaces, or making various other architecture changes to things we would probably have designed differently if this was the major use case we were building for).

I suspect at least some of these use cases will be better served through Nuance in the long run, instead of trying to make the Phabricator core handle them better. I'm not sure if your use case would fit into Nuance or not, but in at least some of these cases clients don't need much access -- mostly just a way to have conversations, report bugs/issues, and get status updates. Nuance gives us a better set of tools for more completely separating users from the Phabricator core, and may serve some of these use cases very well.

Before building tools to improve these use cases, I'd like to build Nuance first. We have a clearer picture of what Nuance should look like and how it should work, and once it's built we'll have a better set of tools to try to solve these "client/partner" problems, and a better idea of exactly how a "Space switcher" should actually work. If we tried to guess today, I'm worried we may end up with a lot of overlap between what Spaces are trying to do and what Nuance ultimately does.

Nuance is on our internal roadmap (we want to move stuff like contact@ and support@ over to it, among other things) but we have a lot of externally prioritized work ahead of it (per above) so I don't have any real idea what the timeline on it is.