Re: [Wikitech-l] Let's talk about arc: On Arcanist docs

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 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(a)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" > > 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_Con… > > 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: > > 1) In the "Overview" there should be some links to basic installation and configuration > (the .arcconfig thing). > > 2) "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. > > 1) 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_Cus… > 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_Rep… > > 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(a)lists.wikimedia.org > https://lists.wikimedia.org/mailman/listinfo/wikitech-l