Come on, Evan, seriously? :-/

I've read that document several times. So obviously it is unclear.

Where further you can go from

I want to be able to become watcher of the project programatically (read: automatically based on some triggerring event) instead of having to add myself manually.

???

It is the root.

In T11405#188030, @epriestley wrote:

How about this: we'll play the "5 whys" game described in Describing Root Problems to get to bottom of this problem. After we figure it out, you tell me why you didn't provide that information in the first place and how to improve the documentation so that it's clear what we're after. Sound good?

Fair enough. I'm totally willing to sprinkle my head with ashes after I'll find out what exactly is causing the misunderstanding of what "root cause" is. ;-) But not knowing it is obviously not helpful and leads to the same situation again.

I want to be able to become watcher of the project programatically (read: automatically based on some triggerring event) instead of having to add myself manually.

Why do you want to become the watcher of a project programmatically?

Not sure what else apart from "instead of having to add myself manually" and "based on some triggerring event" I can say. Perhaps you want to elaborate the event? It can be different. Example 1: Batch edit of more projects at once - obviously easier to run script than having to click it manually. Example 2: Email notification via Herald about new project creation triggers desired watching of such project (that would cover rejected T11312). Example 3: Any other trigger based on some own script, ie. datamining, statistics etc...

PS: If nothing else, then for consistency ;-) You can manipulate subscribers via Conduit, so why not watchers... API should always be able to do the same as (G)UI.

Example 1: Batch edit of more projects at once - obviously easier to run script than having to click it manually.

Why do you need to watch multiple projects at once?

Example 2: Email notification via Herald about new project creation triggers desired watching of such project (that would cover rejected T11312).

Why would making an API call be more convenient than clicking the link in the email and then clicking "Watch Project"?

Example 3: Any other trigger based on some own script, ie. datamining, statistics etc...

Why would a user want to write a script to automatically wathc projects?

Also, please note this:

https://secure.phabricator.com/book/phabcontrib/article/feature_requests/#hypotheticals

We do not build features based on hypothetical use cases, and hypothetical use cases can not be root problems -- since they're hypothetical, they aren't problems.

So saying something like "A user might want..." or "I can imagine..." or similar isn't the right way to answer these questions. You need to answer them with specific, concrete answers based on what real users actually do or need to do, not what theoretical users might hypothetically like to do.