Clarifying Projects as a General Purpose Tool

In Phabricator, "Projects" are designed as a general purpose organization tool. We've made a number of small product and UI changes recently to reinforce this. These changes are primarily focused at new users, who sometimes find the behavior of projects confusing.

For existing users who are already familiar with Phabricator projects, these changes shouldn't have much of an effect. Although these changes have touched a few minor things, everything pretty much works the same way it did before, just with a slightly different UI. Our hope is that the UI is now more clear about what to expect.

The name "projects" can imply a lot of behavior, especially if you're new user coming to Phabricator from another system which has a similar object or concept that behaves differently. In Phabricator, projects are a flexible organizational tool. While they can be used to organize blocks of related work, they can also serve as tags or groups, convey additional state, be used to define policies, or just serve as a hub for related information.

Previously, this wasn't communicated very explicitly, and some of the language and behaviors that projects had implied that they should have a narrower scope than they are intended to. We've made a few changes to make the flexible, general purpose nature of projects more explicit and consistently hinted in the UI. These changes include:

New Documentation: Projects now has a user guide (see Projects User Guide) which explicitly discusses the roles and behaviors of projects. In particular, it is explicit that changing project tags never affects policies, which is the biggest point of confusion we've seen from new users.

Consistent Use of "Tag": We're now more consistent about using the word "tag" to describe associating projects with other objects. For example, objects and search forms now have a "Tags" field, while Maniphest prompts you to "Change Project Tags".

Previously, we used a mixture of different language and some of that language could be misleading. A few UIs implied that objects go "in" projects. While we use this language informally, it can be confusing for new users because it implies a hierarchical or containment relationship which projects do not create.

In other cases, we used "Projects", which wasn't misleading but didn't help dispel any incorrect ideas users had about policy implications. The hope is that "Tags" will be a clearer signal to new users that they aren't altering policies by editing the field.

(There's probably a little bit of old language still kicking around, but we'll clean it up as we find it.)

No Automatic Join on Create: When creating a project, you no longer join it automatically. Instead, a new Initial Members: field allows you to add yourself or other users as members.

The previous behavior made it difficult to create projects with no members and not obvious that this was OK, which served as an undesirable hint about project behavior and taught users that projects should have members. This isn't true and it's reasonable to create projects without any members. The new UI aims to make this more clear.

Icons / Labels: Project icons now have configurable names (like "Tag" and "Group"), and the names and icons are shown in more places in the UI. You can adjust these names in Config by tweaking projects.icons. This labeling and additional flexibility is intended to help reinforce the idea that projects can serve many different roles.

Watch Without Joining: Previously, you needed to join a project to watch it, which led to some situations where project membership was a meaningless side effect of interest in a project. Since T10180, you can watch any project you can see, which should improve the quality and semantics of project memberships going forward.

Written by epriestley on Feb 5 2016, 10:28 PM.
"100" token, awarded by SpaceKees."Love" token, awarded by vinzent.

Event Timeline