Fixes T8487.
Details
- Reviewers
epriestley lpriestley - Group Reviewers
Blessed Reviewers - Maniphest Tasks
- T8487: Link in Documentation Does Not Exist
- Commits
- Restricted Diffusion Commit
rPe74f027f0ac2: Clarifiying Documentation Links
Verify that links are clear at Diviner > Phabricator Contributor Docs > Using the Phabricator OAuth Server.
Diff Detail
- Repository
- rP Phabricator
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Let me know if you would like me to clarify anything.
src/docs/contributor/using_oauthserver.diviner | ||
---|---|---|
38 | I think we need higher-level navigation instructions here. The problem we're trying to solve is two-fold: (1) We want to make it clear that "# Visit <phabricator.example.com>" is not a valid URL. To solve (1), we decided to simply make the link not clickable, as you did in the other example URL's in this file. To solve (2), you need give users a high-level understanding of where the destination lives, relative to the install homepage. Open <your local install URL>/oauthserver/client/create/. Where you will find yourself is on a create page of some application. Your job is to communicate directions to that page in {nav X > Y} format. If you look at the crumbs, in the top left of the page, you'll notice that you are in the "OAuth Server" application. So I would open a separate tab and start navigating to the "Create" page the way a user would, if they were following your instructions. When you open the "OAuth Server" application, you'll notice that directing users to "client" doesn't make sense, because there is no word like that on the page. However, there is something called, "Create Application". When you open that, you should notice that that is the exact URL we've been meaning to reach. So, really, there are three steps the user would need to follow. "Your Local Install", "OAuth Server", "Create Application". Following these steps is the equivalent of navigating to the example URL, but it eliminates any ambiguity, should the example URL cease to be correct in the future. | |
44 | Is there a reason you left off the trailing slash? | |
79 | Here, too? |