Page MenuHomePhabricator

Update diviner support documenation

Authored by chad on Aug 19 2015, 5:35 PM.
Referenced Files
Unknown Object (File)
Mon, Aug 1, 9:30 AM
Unknown Object (File)
Jul 2 2022, 5:01 PM
Unknown Object (File)
Jun 27 2022, 6:50 PM
Unknown Object (File)
Jun 4 2022, 3:27 PM
Unknown Object (File)
May 25 2022, 10:22 AM
Unknown Object (File)
May 25 2022, 10:22 AM
Unknown Object (File)
Dec 23 2016, 2:10 AM
Unknown Object (File)
Oct 6 2016, 5:09 PM



This basically adds Ponder, Stack Overflow, and Conpherence, removes IRC as the "best" option (no real reason to actually turn off IRC at the moment)

Test Plan

Ask Evan if this is cool. Generate documenation, click on links.

Diff Detail

rP Phabricator
Lint Passed
No Test Coverage
Build Status
Buildable 7688
Build 8413: [Placeholder Plan] Wait for 30 Seconds
Build 8412: arc lint + arc unit

Event Timeline

chad retitled this revision from to Update diviner support documenation.
chad updated this object.
chad edited the test plan for this revision. (Show Details)
chad added a reviewer: epriestley.
cburroughs added inline comments.

bikeshed: Maybe list Maniphest last? The cost of confused or not appropriate requests there feels higher than the other places.

I kind of want to remove the "give feedback" part as well. Since, well, we have years worth of feedback already collected haha.

joshuaspence added inline comments.

I think you can just do {Z1336}


That would only work on this server.

My biggest concern right now is that we're not setting expectations appropriately.

I don't think it's a problem that users don't get help: many problems users have amount to wanting extensive, time consuming, expert, personalized help for free. I think it is correct for this help to be unavailable: it doesn't make sense for any member of the upstream or community to spend time providing this help.

I do think it's a problem that we overpromise and underdeliver. IRC is the biggest case of this currently.

I think this revision helps, but still promises users a lot more help than they're likely to actually get.

For example, I don't think we should say this:

Stack Overflow has a great technical community and solid gamification to encourage good questions and answers.

I think this overpromises by making StackOverflow sound better than it is (in practice, I think many questions are bad and many answers are bad).

Maybe something more along these lines?

Bugs and Feature Requests

Intro paragraph is toned down to set expectations better: upstream is busy and has very limited resources. Basically a summary of the linked documents which is more tonally aligned with them.

  • Links to articles.
  • Remove all direct links to Maniphest.

Community Resources

Intro paragraph sets very low expectations about support: community members helping you for purely altruistic reasons.

  • Link to Ponder.
  • Maybe not even a link to chat? Regulars can probably find it on their own.

Maybe Consulting?

This section would just be a link to "Consulting", primarily to help reinforce our valuation of upstream time (i.e., intent is to dissuade users from frivolous interactions by attaching a number to earlier statements about the value of upstream resources, not really to actually provide a support resource).

Maybe Level Requirements?

Possibly restate the "Level Requirements" section of the install guide, or other general stuff there ("bizarre environments", etc)?

The intent of this section would be to reiterate to users that we expect you to have an admin/ops skillset if you're being an admin/op of an instance, that we don't support weird environments, etc. General theory is that lots of users probably ignore this stuff when installing and a reminder (basically, "you were warned, and ignored the warning") might be useful here. Maybe this is the first section and we just restate all the stuff that you won't get any help with. I think it's important that the thrust be "you were warned", not "surprise! it's a trap!", but I think we're generally good about tone/expectations everywhere except this document and the direct links to it.

Maybe Upsell to Phacility?

I generally don't love mixing our commercial stuff into the open source docs, but this might be the best solution for some users. Overall, I'd generally write this with the intent of again reinforcing that support / upstream time are valuable resources, though: trying to dissuade frivolous users, not actually convert users.

Does that generally sound OK? I can draft that out in more detail if it seems broadly reasonable.

I think the big difference is that my primary goal with this document is to set user expectations (which I think is the biggest problem we have now), and actually directing them to resources is a distant secondary goal (I don't think we have a problem with this today, and if anything resources are too easy to find and users arrive with the wrong set of expectations). Does that goal make sense?

We should also maybe rename this to "Support Resources" or something -- I generally agree that "Give Feedback!" is no longer a goal we want to explicitly encourage users toward, as we have many years worth of wonderful feedback already. Our cup runeth over with thick, syrupy feedback.

All that sounds reasonable, happy to just have you take a pass at it since I think you personally provide more support than I do.

On Stack Overflow / Quora / etc... maybe still helpful to provide links? It seems common still that users find answers on these forums and if they already have an account there, may be more easy for them to ask there.

I presume we can build a Stack Overflow Nuance connector down the road if needed.

I'm leaning toward renaming this so I'm going to wait for T9171 to make that easier -- if @joshuaspence doesn't get to it for a bit I'll steal it.