Page MenuHomePhabricator

Clarifiying Documentation Links
ClosedPublic

Authored by SalmonKiller on Jun 10 2015, 9:47 PM.
Tags
None
Referenced Files
Unknown Object (File)
Fri, Dec 13, 9:39 PM
Unknown Object (File)
Fri, Dec 6, 8:53 PM
Unknown Object (File)
Thu, Dec 5, 3:17 AM
Unknown Object (File)
Wed, Dec 4, 4:43 AM
Unknown Object (File)
Nov 27 2024, 7:43 AM
Unknown Object (File)
Nov 22 2024, 11:36 PM
Unknown Object (File)
Nov 19 2024, 2:46 AM
Unknown Object (File)
Nov 14 2024, 10:49 PM
Subscribers

Details

Summary

Fixes T8487.

Test Plan

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

SalmonKiller retitled this revision from to Clarifiying Documentation Links.
SalmonKiller updated this object.
SalmonKiller edited the test plan for this revision. (Show Details)
SalmonKiller edited edge metadata.

Reformatted Links

Reformatted sample links for clarity.

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.
(2) We want to make sure that the navigation instruction you're giving users is immune to trivial URL changes that we might make in the future.

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?

SalmonKiller edited edge metadata.

Fixed inaccuracies pointed out by lpriestley

epriestley edited edge metadata.
This revision is now accepted and ready to land.Jun 14 2015, 2:44 AM
This revision was automatically updated to reflect the committed changes.