Standard for adding troubleshooting links to help articles
Chris Ilias
a level one heading to the bottom, called "Troubleshooting", and list in
point form, any articles that address any problems people may have,
relating the content of the current article.
For instance, at the end of
<http://support.mozilla.com/kb/Customizing+your+Firefox+with+add-ons>, put:
!Troubleshooting
*((Unable to install add-ons))
Jason Barnabe (np)
I think it would be more useful to have links to troubleshooting
articles at the point in the text where the user would see the
problem. I'm not confident users would notice the links if they were
at the bottom.
David Tenser
Assuming this was a suggestion, the problem I see with it is that it
would mean a lot of maintenance and manual updating of articles, as more
troubleshooting articles are added.
We already use tags on our articles. Wouldn't it be better if a Help
article could have an automatically generated list of Support articles?
(For the definition of Help and Support articles, see
http://wiki.mozilla.org/Support:PRD#Content_Types)
David Tenser
While I agree that would make more sense, it would pretty much rule out
any automatic generation of the list.
It would be cool if it could be more prominently visible than having a
list at the bottom of the article. No one with a problem will scroll
down to the bottom. Maybe it has its place in the sidebar?
Majken Connor
_______________________________________________
support-planning mailing list
support-...@lists.mozilla.org
https://lists.mozilla.org/listinfo/support-planning
I like the bottom idea myself. If people are troubleshooting they should be getting to the troubleshooting article first in their search. I think within the article, if we mention an issue we can link to it using a footnote or like link [here] (forget what that's called). then having a complete list at the bottom lets us use the whole article title without cluttering up the information.
Jason Barnabe (np)
> I like the bottom idea myself. If people are troubleshooting they should be
> getting to the troubleshooting article first in their search.
If we assume that people are reaching the troubleshooting article
first, then it's irrelevant what we do because they're finding their
information. But people aren't finding the troubleshooting article as
evidenced by the feedback we get.
> I think
> within the article, if we mention an issue we can link to it using a
> footnote or like link [here] (forget what that's called). then having a
> complete list at the bottom lets us use the whole article title without
> cluttering up the information.
I don't understand. Why would we link to a footer which links to the
article instead of linking to the article directly?
Majken Connor
_______________________________________________
you're right, I didn't mean an actual footnote, but the little thing that denotes a link like mediawiki has.
Jason Barnabe (np)
Can you give an example of how you would use this? Let's say we're
giving instructions on how to install an extension, and the user has
just restarted so their extension should work. How would you link to
an article describing reasons why it wouldn't work?
Majken Connor
_______________________________________________
support-planning mailing list
support-...@lists.mozilla.org
https://lists.mozilla.org/listinfo/support-planning
I guess my suggestions are really two visuals for doing the same thing. Basically you'd say something like "if this doesn't work, you might be having x problem" and then some of that is linking to the troubleshooting doc. Saves us from adding the "this article explains x" which can get wordy, especially if it's an article that covers something that has a lot of issues.
As a user I prefer having the troubleshooting links together, because then I can see which one sounds most like what I need. I don't know if that's typical or not. I tend to read as little as I need to, and I know that's a common thing, although where I look might be influenced by my being a more advanced user.
Do we have examples of what articles aren't being found? Can we look at their introductions to see if maybe that can be optimized?
Chris Ilias
How about a troubleshooting list at the end of section?
Chris Ilias
> On Oct 12, 8:24 pm, "Majken Connor" <maj...@gmail.com> wrote:
>> I like the bottom idea myself. If people are troubleshooting they should be
>> getting to the troubleshooting article first in their search.
>
> If we assume that people are reaching the troubleshooting article
> first, then it's irrelevant what we do because they're finding their
> information. But people aren't finding the troubleshooting article as
> evidenced by the feedback we get.
I may be mistaken, but I think all such feedback is coming from articles
listed on the front page. Particularly the "Installing..." articles.
Jason Barnabe (np)
Yeah, that's fine. As long as it's somewhere near the actual actions
that would cause the problem.
Chris Ilias
https://bugzilla.mozilla.org/show_bug.cgi?id=400052
(Congrats to timeless for reporting bug 400000. :-) )
David McRitchie
> On 10/15/07 7:32 PM, _Jason Barnabe (np)_ spoke thusly:
>> On Oct 15, 5:41 pm, Chris Ilias <n...@ilias.ca> wrote:
>>> How about a troubleshooting list at the end of section?
>>
>> Yeah, that's fine. As long as it's somewhere near the actual actions
>> that would cause the problem.
> https://bugzilla.mozilla.org/show_bug.cgi?id=400052
According to that the problem shooting would be at the end
of each section of the article. If you can't have the problem
shooting all at the end of the article, I would think the article
itself would be questionable.
As far as anything in the right column is concerned that is not
done for readability, in my opinion, it is irritating as a reader
to have that stuff there. The good purpose that it serves as I
see it is that it makes it easy for people to update a wiki and
to show that they can update a wiki, after using them. For
that purpose the Mozillazine wiki right column works. The
comic book approach here with tags and other stuff in the right
column and non businesslike feedback stuff at the end is
crapola (not a four letter word). The popularity of an article
should be of little interest, if you need it then it's there, if it's
not the article you are search for they should look for another
but you can't draw valid conclusions on the true scope of
an article based on the number of readers, feedback.
--
HTH,
David McRitchie http://www.mvps.org/dmcritchie/firefox/firefox.htm
Jason Barnabe (np)
> The
> comic book approach here with tags and other stuff in the right
> column
We're changing how this stuff works. Fewer talky bubbles, more useful
things on the right.
and non businesslike feedback stuff at the end is
> crapola (not a four letter word). The popularity of an article
> should be of little interest, if you need it then it's there, if it's
> not the article you are search for they should look for another
> but you can't draw valid conclusions on the true scope of
> an article based on the number of readers, feedback.
I agree. The feedback is intended to be read by contributors. Only
logged in users see it. Right now we have no differentiation between a
contributor who's logged in and an end user who's logged in. That's
something else we'll have to solve.
David McRitchie
> I agree. The feedback is intended to be read by contributors. Only
> logged in users see it. Right now we have no differentiation between a
> contributor who's logged in and an end user who's logged in. That's
> something else we'll have to solve.
I actually meant the part that the reader sees. A plain deemphasized
input box would be a lot nicer, and leave out the Yes/No because
the information entered is going to do something perhaps on one
or more of these.
1) suggest improvements
2) indicate how something is unclear
3) completely off the wall because the person is lost
4) misleading due to keywords or search,
5) comment spam, which is nowhere near as bad as
when they can change the content of the wiki itself.
In other words, it doesn't make much difference what the
quality was, if it gets improved it no longer the same and
it is better. If it can't be improved for a long time they it
was the best in it's time and gets improved again when needed.
Hopefully the login problem gets fixed, thought it was just me.
Majken Connor
David McRitchie
That wasn't intended as a radio box, just the type of responses
that you might find in the comments box, heck I'd never want
anyone to choose spam. What I'm trying to say is the that any
such scalable statistical stuff is so fleeting that it is useless
information, it's what's in the text box that counts. If you could
get feed back on the update made for that person that might
lead to more improvement, but again anything such as a score
is so fleeting.
Chris Ilias
As I understand it, the poll is to help us determine which articles are
in most need of improvement.
David Tenser
> I actually meant the part that the reader sees. A plain deemphasized
> input box would be a lot nicer, and leave out the Yes/No because
> the information entered is going to do something perhaps on one
> or more of these. 1) suggest improvements
The yes/no provides us with valuable measurable statistics that allow us
to determine if our articles are good or bad. The extra feedback box
also gives the reader an opportunity to explain _why_ it wasn't bad (or
why it was good, but what could be improved).
So, the yes/no should definitely not be removed. And at this early
stage, we shouldn't redefine it to something else either, although I
would be open to try that in the future when we have collected some data.
The current layout is of course horrible. But we're working on that. :)
David
David Tenser
>
>
> As far as anything in the right column is concerned that is not
> done for readability, in my opinion, it is irritating as a reader
> to have that stuff there. The good purpose that it serves as I
> see it is that it makes it easy for people to update a wiki and to show
> that they can update a wiki, after using them. For that purpose the
> Mozillazine wiki right column works.
The purpose (at least as I view it) is to offer the user more
information that is related to the article, but is not part of the
article itself. For example, the blurb we call "More like this" (would
suggest to rename it to "Related articles").
> The
> comic book approach here with tags and other stuff in the right
> column and non businesslike feedback stuff at the end is crapola (not a
> four letter word). The popularity of an article
> should be of little interest, if you need it then it's there, if it's
> not the article you are search for they should look for another
> but you can't draw valid conclusions on the true scope of
> an article based on the number of readers, feedback.
That's what the article score is about, which is something we (the
community) use as a tool to measure the quality of the content. The
number of page visits is also valuable data because it shows us what
pages our visitors end up at most of the time. Of course, that in itself
is useless if we can't determine the bounce rate and average session
length. We are working to gather a number of metrics that allow us to
measure the quality of our content, using third party tools as Google
Analytics as well as TikiWiki's built-in article score.
That said, the "comic book" _design_ is IMHO plain fugly and we should
work on finding a better way to present the information we want.
Also, there are some elements on a KB article that we really don't want,
such as the tag cloud, which confusingly enough shows all available tags
in the system, while pointing to the current article, suggesting that
the article has those tags.
David
Majken Connor
_______________________________________________
support-planning mailing list
support-...@lists.mozilla.org
https://lists.mozilla.org/listinfo/support-planning
No I wasn't saying your suggestion was a radio box, I'm talking about the existing "Was this helpful?" radio box.
Majken Connor
David McRitchie wrote:
> I actually meant the part that the reader sees. A plain deemphasized
> input box would be a lot nicer, and leave out the Yes/No because
> the information entered is going to do something perhaps on one
> or more of these. 1) suggest improvements
The yes/no provides us with valuable measurable statistics that allow us
to determine if our articles are good or bad.
Just to make sure my reply to the other David doesn't get lost, I disagree with this. The question is too vague. It collects too many answers at once. Some people will check "no" if it was the wrong article. Some people will check "no" if they didn't understand the solution. Some people will check "no" if the solution flat out didn't work. Having all this information in one number that we can't sift through doesn't help us much at all. We'll end up ignoring it and just watching the feedback.
If we change the question to "did this article solve your problem" then we can follow the user from search term to the article they finally click yes on, and we can see what articles those search terms are turning up that the user is clicking on rather than the right article.
The feedback field will still serve to tell us when an article that's right is confusing, as will the forums, and the forums will also tell us when a solution isn't in the article.
We should split this conversation off, though. Was there an earlier discussion about the "Was this article helpful?" bits that we could pick back up? Or did we settle the troubleshooting bit already?
David McRitchie
> On 10/18/07, David McRitchie <dmcri...@hotmail.com> wrote:
>>
>> "Majken Connor" <maj...@gmail.com> wrote in message news:
>> mailman.2865.119267843...@lists.mozilla.org...
>> > I'm actually with you on this one, so we must be right ;) Although, I'd
>> > like to put it one step more. I think the yes/no is helpful, but I
>> think
>> > we're asking the wrong question. I think what we want to be asking is
>> "Did
>> > this article solve your problem" then we can follow a user's path and
>> look
>> > at their search terms and see what article they're *Trying* to get to,
>> and
>> > see which articles they hit on the way. That's the only helpful thing
>> that
>> > radio box can really tell us.
>>
>> That wasn't intended as a radio box, just the type of responses
>> that you might find in the comments box, heck I'd never want
>> anyone to choose spam. What I'm trying to say is the that any
>> such scalable statistical stuff is so fleeting that it is useless
>> information, it's what's in the text box that counts. If you could
>> get feed back on the update made for that person that might
>> lead to more improvement, but again anything such as a score
>> is so fleeting.
>
> existing "Was this helpful?" radio box.
Okay, that's good.
Jason Barnabe (np)
> If we change the question to "did this article solve your problem" then we
> can follow the user from search term to the article they finally click yes
> on, and we can see what articles those search terms are turning up that the
> user is clicking on rather than the right article.
Tutorial articles don't exist to solve problems. Troubleshooting
articles don't necessarily solve problems either; they can sometimes
be "sorry, there's no way to do that.".
Majken Connor
Well how about "Did this article answer your question?"
Jason Barnabe (np)
-That assumes the user had a question.
-I'm leery of referencing "questions" because it may result in people
expecting their question to be answered in the feedback area.
-I don't see how this solves the problems you have with the current
wording.
David Tenser
I agree with Jason and was about to post a similar response. There's
nothing that says changing the question to "Did this article solve your
problem?" or "Did this article answer your question?" would give us more
meaningful data.
However, you are right (Lucy) that the question we ask now _could_ give
us kinda crappy data, but let's actually gather some data first to
evaluate it before we deem it crappy.
David
Majken Connor
If they weren't searching to answer a particular question then do we want to collect that data with that mechanism? If they weren't searching with a particular question, but they found a really horribly written article, or an article that they knew was missing data then they'd want to fill out the feedback field anyway, not just the radio button.
David Tenser
> "helpful" isn't a concrete word, it's not quantifiable. chofmann
> mentioned this earlier. People might be reluctant to click no because it
> was a well written article but wasn't the one they were looking for, or
> it gave them a hint towards finding the solution.
>
> If they weren't searching to answer a particular question then do we
> want to collect that data with that mechanism? If they weren't searching
> with a particular question, but they found a really horribly written
> article, or an article that they knew was missing data then they'd want
> to fill out the feedback field anyway, not just the radio button.
>
I agree that "helpful" is a vague term that is very subjective.
However, I don't agree that it's not quantifiable. To give a stupid
analogy: if we had a site with photos of people and asked the question
"Is this person sexy?", the data we collected would still be subjective
and based on a vague term. Nevertheless, you would notice how some
people got a significantly higher score, while other people got a much
lower score. The same applies to the kb articles.
The problem here, I guess, is that there can be more than one reason why
an article is (not) helpful. For example, the reader might have stumbled
upon the wrong article, or the article didn't solve the *right* problem,
or it was poorly written, or it covered the right problem, but still
didn't solve it.
But... I don't see how rewording the question to something else would
make the data any better? As discussed earlier, changing it to your
proposals introduce other problems.
David Tenser
> However, I don't agree that it's not quantifiable.
What I mean with "quantifiable" in this context is "useful to us".
Majken Connor
Changing the wording doesn't introduce other problems, per se. It reduces the number of metrics we're collecting to simply "this is the article the person was looking for when they initiated contact with the site" We have no other way to collect this metric, and all the others that are being covered with the current wording can be collected from the feedback panel, which people will use if they didn't understand something. Alternately, if a person's search terms or eventual comment show that they were looking for content that already exists, we can see if they got to the article and clicked "no."
Basically, with the current question (unless we expand the options to include things like "no, I couldn't understand it) we're not getting anything useful. We'll see if an article is getting a low rating, but we won't be able to see why without looking at the comments. If that's the case then let's either ditch it altogether or force people to submit a comment as well as the karma.
Chris Ilias
> On any Help article (Reference chart, feature tutorial, or how-to), add
> a level one heading to the bottom, called "Troubleshooting", and list in
> point form, any articles that address any problems people may have,
> relating the content of the current article.
>
> For instance, at the end of
> <http://support.mozilla.com/kb/Customizing+your+Firefox+with+add-ons>, put:
>
>
> !Troubleshooting
> *((Unable to install add-ons))
A couple of examples:
http://support.mozilla.com/kb/Installing+Firefox+on+Windows
http://support.mozilla.com/kb/Upgrading+Firefox
David Tenser
> that's a bad example, while what is sexy to one person isn't to another,
> people know what they're supposed to be answering when asked that.
>
> Changing the wording doesn't introduce other problems, per se. It
> reduces the number of metrics we're collecting to simply "this is the
> article the person was looking for when they initiated contact with the
> site" We have no other way to collect this metric, and all the others
> that are being covered with the current wording can be collected from
> the feedback panel, which people will use if they didn't understand
> something. Alternately, if a person's search terms or eventual comment
> show that they were looking for content that already exists, we can see
> if they got to the article and clicked "no."
I still don't see how it would make the data any better. Even if we
reworded it to "Did this article solve your problem?", we still don't
know if the visitor a) had a problem in the first place, b) came to the
right page for the problem he/she had, c) didn't understand the article
because it was poorly written.
If someone visits the support page, discovers the "Top 10" list and
clicks on "Lost Bookmarks" out of curiosity, how useful will the
gathered data be when he/she clicks No because of a) above?
If someone has lost his/her bookmarks, searches for "bookmarks gone",
clicks on the first search result [1], how useful will the gathered data
be when he/she clicks No because of b) above?
[1] http://support.mozilla.com/kb/Uninstalling+add-ons
Furthermore, the question "Did this article solve your problem?" will
simply not apply for tutorial, references, and many how-tos. This means
we won't have any quantifiable data for those kind of articles. These
are the articles that we want to show in the in-product help and as such
are very important, even though they don't solve particular "problems".
(Possible solution: different questions for different article types.)
You also say that all other data can be gathered from the feedback
panel. That's non-quantifiable data which requires someone to actually
skim through it, and as such can't be used as a weekly metrics to
determine whether or not we are successful in providing support. We want
measurable data. (See also below.)
>
> Basically, with the current question (unless we expand the options to
> include things like "no, I couldn't understand it) we're not getting
> anything useful.
And that might well be the solution. I will talk to our enumerator
tomorrow about how we can make the data gathered better. We might want
to ask more questions, or provide more options. Maybe even checkboxes, e.g.
[ ] This article solved a problem I had with Firefox.
[x] This article was well written.
[X] This article was a great inspiration for a book I'm writing.
> We'll see if an article is getting a low rating, but we
> won't be able to see why without looking at the comments. If that's the
> case then let's either ditch it altogether or force people to submit a
> comment as well as the karma.
>
Too early for decisions like that. I think the discussion here is
interesting and important, but even if you're 100% right that the data
gathered is absolutely useless, the solution is not to remove it
altogether, but to fix it.
David Tenser
I hate to be Mr Negative here but I can't say I like it very much. It
generally feels misplaced and also clutters the table of contents.
What do other people think?
Jason Barnabe (np)
I think it would be good to lose the heading and good descriptions of
the problem in the context of the article. Instead of:
!Troubleshooting
* Cannot connect after upgrading Firefox
* SSL is disabled
Something like:
__Having problems?__
* Firefox can't reach web sites any more
* Firefox says SSL protocol is disabled when I go to certain sites
(Actually that second one could stand to have a better article name
anyway)
Jason Barnabe (np)
wrote:
> I think it would be good to lose the heading and good descriptions of
> the problem in the context of the article. Instead of:
By this I mean
-lose the heading
-add good descriptions
David Tenser
Still, the main concern here is that we need continuos manual editing of
articles. It will scale as the content ramps up, especially when we do l10n.
We currently have two different kinds of articles, help, and support.
[1] Is it not better to have a "Troubleshooting" section in the new
sidebar, that would be standard for all help articles?
[1] http://wiki.mozilla.org/Support:PRD#Content_Types
This manual inserting of support references in help articles is not a
bad thing in itself, it just means more work for us for something that
_could_ be automated.
David Tenser
> Furthermore, the question "Did this article solve your problem?" will
> simply not apply for tutorial, references, and many how-tos. This means
> we won't have any quantifiable data for those kind of articles. These
> are the articles that we want to show in the in-product help and as such
> are very important, even though they don't solve particular "problems".
> (Possible solution: different questions for different article types.)
After a meeting with mconnor, this indeed seems to be a viable solution.
> You also say that all other data can be gathered from the feedback
> panel. That's non-quantifiable data which requires someone to actually
> skim through it, and as such can't be used as a weekly metrics to
> determine whether or not we are successful in providing support. We want
> measurable data. (See also below.)
The solution here could be to have two separate questions. One "Did this
article solve your problem?"/"Was this the information you were looking
for?", and one "Is this article well written?" (or something similar).
>
>>
>> Basically, with the current question (unless we expand the options to
>> include things like "no, I couldn't understand it) we're not getting
>> anything useful.
>
> And that might well be the solution. I will talk to our enumerator
> tomorrow about how we can make the data gathered better. We might want
> to ask more questions, or provide more options. Maybe even checkboxes, e.g.
We also talked about this, to progressively provide more granularity if
a user clicks No. I will summarize the meeting and post a new thread
about it asap.
Jason Barnabe (np)
> We currently have two different kinds of articles, help, and support.
> [1] Is it not better to have a "Troubleshooting" section in the new
> sidebar, that would be standard for all help articles?
As a user, if I encountered a problem, I would want the help to be
exactly at the step that I would encounter it.
1. Press "Foo". The "Bar" dialog should come up.
** "Bar" didn't come up? Read ((this article)).
2. In "Bar", press...
If this content was only on the sidebar, I may not think to look
there. It may not even be on screen. I wouldn't think to scroll up to
find a solution, though I might scroll down. As part of the article
text, I would definitely see it.
Generally, for anonymous users, I believe the sidebar should be a
method of going to other topics before they get too far into the
current topic. For example, someone who lost their bookmarks might end
up at the "Bookmarks" article, but might really want to go to "Lost
Bookmarks". We have this function already. Alternately, the user might
decide to go in a completely different direction. This is what search
is for.
> This manual inserting of support references in help articles is not a
> bad thing in itself, it just means more work for us for something that
> _could_ be automated.
In addition to the above objection, I'm not confident that something
automated could determine the correct articles to link to.
Majken Connor
On Oct 19, 1:32 pm, David Tenser <djst.mozi...@gmail.com> wrote:
> We currently have two different kinds of articles, help, and support.
> [1] Is it not better to have a "Troubleshooting" section in the new
> sidebar, that would be standard for all help articles?
As a user, if I encountered a problem, I would want the help to be
exactly at the step that I would encounter it.
I agree with you on this one. The only reason for it to be anywhere else is that the user knows they're looking for a trouble shooting article, but landed on the tutorial article instead (therefore they don't want to read the whole thing, just want to find the troubleshooting links). In which case the solution is to make sure the right articles are turning up at the top of the search results.
David Tenser
> On Oct 19, 1:32 pm, David Tenser <djst.mozi...@gmail.com> wrote:
>> We currently have two different kinds of articles, help, and support.
>> [1] Is it not better to have a "Troubleshooting" section in the new
>> sidebar, that would be standard for all help articles?
>
> As a user, if I encountered a problem, I would want the help to be
> exactly at the step that I would encounter it.
>
Yes, if we we're providing step by step instructions and know that a
common problem can occur at a specific step, it makes sense to have the
information there.
> 1. Press "Foo". The "Bar" dialog should come up.
> ** "Bar" didn't come up? Read ((this article)).
> 2. In "Bar", press...
>
Right.
> If this content was only on the sidebar, I may not think to look
> there. It may not even be on screen. I wouldn't think to scroll up to
> find a solution, though I might scroll down. As part of the article
> text, I would definitely see it.
>
> Generally, for anonymous users, I believe the sidebar should be a
> method of going to other topics before they get too far into the
> current topic. For example, someone who lost their bookmarks might end
> up at the "Bookmarks" article, but might really want to go to "Lost
> Bookmarks". We have this function already. Alternately, the user might
> decide to go in a completely different direction. This is what search
> is for.
>
>> This manual inserting of support references in help articles is not a
>> bad thing in itself, it just means more work for us for something that
>> _could_ be automated.
>
> In addition to the above objection, I'm not confident that something
> automated could determine the correct articles to link to.
>
I was thinking a tag based query of troubleshooting articles. But I
agree with what you say above. The automatic sidebar listing of
troubleshooting articles could still be a good thing to have though.
Chris Ilias
> On Oct 19, 1:32 pm, David Tenser <djst.mozi...@gmail.com> wrote:
>> We currently have two different kinds of articles, help, and support.
>> [1] Is it not better to have a "Troubleshooting" section in the new
>> sidebar, that would be standard for all help articles?
>
> As a user, if I encountered a problem, I would want the help to be
> exactly at the step that I would encounter it.
>
> 1. Press "Foo". The "Bar" dialog should come up.
> ** "Bar" didn't come up? Read ((this article)).
> 2. In "Bar", press...
Sorry for dropping the ball on this. This is something I've wanted to
make considerable progress on this week.
It's clear that we have a range of possible circumstances, where one
standard is not best for all articles. The method above works, when
there's on problem; but if someone clicks on Check for Updates, there
are a number of articles we will need to cite. I also fear that this
method may be cluttering articles.