Page MenuHomePhabricator

Arcanist setup documentation is circular
Closed, ResolvedPublic


Reading the arcanist documentation at

First thing I need is to install, so I follow the QuickStart link at the top.

But this document says that detailed installation instructions are back at the previous document. It offers a link to platform specific instructions, though, so I click through to the MacOS link
This again refers the user back to the original page for the actual arcanist installation instructions.

After a while clicking around in circular links, and because I'm ex-FB, I stopped to look, and the installation instructions are on the 'Quick Start Guide' page below the links to platform specific instructions.

Highly confusing.

Event Timeline

Thanks! I guess nobody ever noticed that before!

There's a short version and a long version. Each version links to the other version, saying "here's a different version of these instructions, if you'd prefer that one". How could we make this more clear?

That is, this passage:

For detailed instructions on installing Arcanist, see Arcanist User Guide.

  • For Mac OS X, see Arcanist User Guide: Mac OS X.
  • For Windows, see Arcanist User Guide: Windows.


You are currently reading the quick instructions for installing Arcanist. If you'd like more detailed instructions instead, see the full guide, or one of the more detailed links in the list immediately below:

  • For more detailed instructions that include instructions particular to OSX, see this more detailed OSX-specific guide.
  • For more detailed instructions that include instructions particular to Windows, see this more detailed Windows-specific guide.

I'm assuming he wants us to duplicate the installation information onto Win/Mac pages or only link to those pages after installing arcanist.

Oh, no, it's just to do with the ordering of the links vs the annotations: if you're totally new to phabricator, you're going to get tripped on the "quick start" link which says "install stuff" and in the middle links you back two pages...

Give me until tomorrow, I'll suggest a change?

Maybe the "Install Arcanist" header on Quick Start could be like:

Other Versions Of This Document

If you just googled this and would rather read more words, here's the other document: ...

  • osx
  • windows

Okay, Actually Installing Arcanist

I agree that the current header/section organization are a little funky/misleading.

So I don't forget:

On the Arcanist Quick Start page, move
"For detailed instructions on installing Arcanist, see Arcanist User Guide."
from immediately below "Install Arcanist" to the section above it. Otherwise it seems like a link you need to click to perform the install.

The Mac OSX and Windows "guide" links might be better placed after the installation instructions. So that the flow would be:

. Install Pre-requisites (php, git),
. Install arcanist
... steps ...
. Additional steps
... path ...
... links to OS X and Windows additional instructions ...

@epriestley Yep - like what you're doing there :)