Thanks, this is helpful. We plan to eventually move Diviner (the documentation generator) into Phabricator itself and I want to do that before making significant layout/style/organizational changes so I'm not going to hit all these points immediately, but some of the things you point out are just dumb on our part and easy to fix. I sent out a couple of diffs that should improve things:
https://secure.phabricator.com/D3235 https://secure.phabricator.com/D3236
(btw. Defined: src/docs/userguide/arcanist.diviner:1 seems useless to the causual onlooker).
For slightly-less casual onlookers who spot a typo, it's a good way for them to know how to fix it. :)
Evan
On Aug 10, 2012, at 12:26 AM, Marcin Cieslak wrote:
Evan Priestley epriestley@phacility.com wrote:
I sent out a diff to fix the error message (https://secure.phabricator.com/D3231), the new one reads:
This patch is for the 'phabricator' project, but the working copy does not have an '.arcconfig' file to identify which project it belongs to. Still try to apply the patch?
We're trying to catch the case where you're attempting to apply a patch to the wrong project -- I'm guessing revision D3 was made in a working copy with a .gitignored ".arcconfig" file that associates it with "E3Experiments". If you check in the ".arcconfig" file, arc will be able to recognize the working copy's project and will stop complaining.
I realize my probleme where related to the E3Experiments not having .arcconfig
I started suspecting E3Experiments is kind of unconfigured when "arc git-hook-pre-received" hinted me about this:
"Usage Exception: You have installed a git pre-receive hook in a remote without an .arcconfig.")
What could we improve about the user guide?
First, I found two entry points:
- Arcanist User Guide
http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide.html
Frankly, I don't remember I how I came to this one.
The problem here is that there is no full table of contents of the "User Guide" (btw. Defined: src/docs/userguide/arcanist.diviner:1 seems useless to the causual onlooker).
I could find this:
http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide_arc_...
But not much more. While writing this email I discovered
http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide_Conf...
hidden in the arc_diff guide which was like tl;dr to me - I didn't know I needed to learn about "arc diff" command to find out about .arcconfig and stuff.
Suggestions for improvement:
- In the "Overview" there should be some links to basic installation and configuration
(the .arcconfig thing).
- "Arcanist allows you to do things like" should explain more about the commands -
descriptions are too short. There are no links to explanations of particular commands (certainly "arc diff" has one).
Coming from gerrit I kind of looked for equivalent of "git fetch ... refs/changes/CD/ABCD/1" and "git push ... refs/for/master". From the terse description there I could sense that "arc diff" does something to push the changes for review and "arc patch" fetches the change from the repo (although "arc export" sound nice, too). Unfortunately, "arc download/upload" do something different :)
- Arcanist Something - Table of Contents
http://www.phabricator.com/docs/arcanist/
The good thing is that Phabricator installation has links to this document at https://phabricator.wmflabs.org/apps/. This is a big plus.
This the Arcanist Something guide is confusing because it contains 95% of developer API documentation. I hoped to find info about .arcconfig in "ArcanistConfiguration" or "ArcanistSettings" but both were disappointing.
Now I see I should go into ArcanistOverview but somehow I missed that. It links to Arcanist_User_Guide_Configuring_a_New_Project which I missed so badly yesterday.
- Probably ArcanistOverview should be *the* front page for the documentation
and the User Guide with full Table of Contents of all docs. Maybe the TOC should be on all "User Guide" pages.
API pages should be clearly marked. Use different skin if possible (red instead of blue:) or clearly mark links to API and UserGuide articles differently (consistent title names? we can't rely on colors or icons). Javadoc output might be ugly, but at least I know immediately "uh oh I ended up in the developer documentation".
There is some problem with http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide_Cust... it sounds like the gentle introduction into the whole API stuff. Not sure yet how it fits to the casual user.
And then, there is
http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide_Repo...
deals only with SVN. "arc git-hook-pre-receive" sounds promising but I have no idea where to find out more about it.
Unfortunately, Phabricator docs use "workflow" as a slang description of some piece of code, so I could not find out "How a typical workflow with arc looks like" and "How installing a git hook changes my workflow".
In general: docs seems to aimed either at the advanced person looking to write "workflows" or "classes" for linting/whatever or for the user of the already pre-configured repository. I would review this again in view of the "lonely wolf" developer that has some (maybe her own repository) and tries to set up this thing. I didn't look at the rest of the Phabricator docs yet but I'd be happy to find guides for "How do I switch to Phabricator with a github/sourceforge/whatever project".
//Saper
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l