Advertisement:

Author Topic: User driven education  (Read 5613 times)

Offline Joshua Dickerson

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 12,666
  • Gender: Male
    • joshuaadickerson on LinkedIn
User driven education
« on: September 10, 2010, 02:52:08 PM »
That's the Doc Team's new motto. We are here to push "user driven education."

The user drives:
  • what needs to be documented
  • what gets documented
  • the action of documenting
  • the search for the educating article
Need help? See the wiki. Want to help SMF? See the wiki!

Did you know you can help develop SMF? See us on Github.

How have you bettered the world today?

Offline Angelina Belle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,589
Re: User driven education
« Reply #1 on: January 12, 2011, 10:33:57 AM »
What if the user is a n00b, and doesn't know how to search for the educating article, because they don't know enough of the right search keywords to find what they need?
Never attribute to malice that which is adequately explained by stupidity. -- Hanlon's Razor

Offline Joshua Dickerson

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 12,666
  • Gender: Male
    • joshuaadickerson on LinkedIn
Re: User driven education
« Reply #2 on: January 12, 2011, 05:59:47 PM »
They drive what needs to be documented. By that, they drive what gets documented. Their questions create 1/2 of the FAQ piece, thus they've just created documentation, and they search for the article. Everyone, from the top to the bottom is addressed in this. Obviously, somethings are easier to say that one type of person has more responsibility than the other, but everyone holds responsibility in all aspects.
Need help? See the wiki. Want to help SMF? See the wiki!

Did you know you can help develop SMF? See us on Github.

How have you bettered the world today?

Offline Angelina Belle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,589
Re: User driven education
« Reply #3 on: January 12, 2011, 06:51:50 PM »
So we need to cruise the support boards looking for new FAQs to write?
Never attribute to malice that which is adequately explained by stupidity. -- Hanlon's Razor

Offline Joshua Dickerson

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 12,666
  • Gender: Male
    • joshuaadickerson on LinkedIn
Re: User driven education
« Reply #4 on: January 12, 2011, 08:40:42 PM »
That's something that the support team should be doing to alleviate the requirements on them to give support constantly. Unfortunately, they haven't been doing this. Hopefully, with time, this will change. We can do it, but our role is more to push other people to do it and we edit it. The main reason for this is because we aren't necessarily the "subject matter experts" nor do we know how best to pose a question. We edit it to ensure that grammar, spelling, and structure of the page is correct.

Most FAQs should be as simple as either a redirect to the page/anchor with the pertinent information or several sentences. Usually, when a question is asked, if you were to reply with a proper answer, you'd already be writing documentation. It would be best for them to take the question, navigate to the page with the question as the title of the page, write their answer (thus creating the page), and then answer the person's question by linking them to the page that they just created.

I've already created a couple of FAQs using this method. Not only does it drive people to read documentation but it also promotes better answers and more abundant documentation.
Need help? See the wiki. Want to help SMF? See the wiki!

Did you know you can help develop SMF? See us on Github.

How have you bettered the world today?

Offline Angelina Belle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,589
Re: User driven education
« Reply #5 on: January 13, 2011, 07:37:05 AM »
Maybe the support team can be trained, at least, to make a request for documentation, with links to relevent support topics.
Then, anybody can view that queue, write, ask for information, improve the document.
The queue shuould probably be automagically viewable from the Doc Helper's Portal on the wiki, because they are our best hope of getting new topics like this written.

So this discussion should be moved to the doc helpers board.
Never attribute to malice that which is adequately explained by stupidity. -- Hanlon's Razor

Offline Norv

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 18,313
  • Blue Wolf
Re: User driven education
« Reply #6 on: January 13, 2011, 07:42:12 AM »
You may want to check as well an older topic on the same issue: Common Support Questions for The Online Manual
To-do lists are for deferral. The more things you write down the later they're done… until you have 100s of lists of things you don't do.
File a security report | Developers' Blog | Bug Tracker

Also known as Norv on D* | Norv N. on G+ | Norv on Github

Offline Angelina Belle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,589
Re: User driven education
« Reply #7 on: January 13, 2011, 07:57:20 AM »
This is a nice discussion thread.  I vote we move it to the doc helper board.
Never attribute to malice that which is adequately explained by stupidity. -- Hanlon's Razor

Offline Norv

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 18,313
  • Blue Wolf
Re: User driven education
« Reply #8 on: January 13, 2011, 08:07:14 AM »
I have no qualms.
The link above is accessible to the Community Helpers group, which is a freely joinable group to my knowledge, so if anyone doesn't see it and wishes to, they can join it.

Moving it.
To-do lists are for deferral. The more things you write down the later they're done… until you have 100s of lists of things you don't do.
File a security report | Developers' Blog | Bug Tracker

Also known as Norv on D* | Norv N. on G+ | Norv on Github

Offline Illori

  • Doc Coordinator
  • SMF Master
  • *
  • Posts: 36,472
Re: User driven education
« Reply #9 on: January 13, 2011, 08:26:16 AM »
i have not read though the wiki in great detail but several questions that come up often:

How do I upgrade my smf to xxx version?

How do I _down_grade my smf install to 1.1.*?

Why is my database backup not complete? this is when doing a backup from the admin panel not from phpmyadmin

Why do I get permission errors when trying to install a package? e.g. missing the temp folder in packages

Often users are asking questions about mods they have installed in the smf specific boards and not in their support threads, maybe a wiki page explaining why smf does not directly support the mod could be useful.

I have seen several people attempt to attach mods they have modified to a post, then to have to be told that this is not allowed, a wiki page on this policy could be helpful... I would suggest such a page be locked from general editing though.

Several users recently have posted about crashed database tables, a wiki page explaining how to repair such would be helpful.

A page on how to move an smf install from one host to another, or from one folder to another and running repair_settings.php

Possibly a general [locked] page on what to consider when giving out your admin/ftp/cpanel login information to anyone to assist in getting issues resolved.

there might be already a page on how to enable/change version emulation for smf 2.0 then reset it back to normal in order to install mods that are not already updated.

instructions on where that check box is for installing mods on other themes, or at least attempting to install it

what this mod does http://custom.simplemachines.org/mods/index.php?mod=2054 and how to properly use it when requested to use it and post the new error logs.

I have seen several issues with the pretty urls mod when people change servers or move their install, maybe that issue could make the wiki faqs

Offline Aleksi "Lex" Kilpinen

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 15,430
  • Gender: Male
  • The Artist Formerly Known as LexArma
Re: User driven education
« Reply #10 on: January 13, 2011, 08:30:24 AM »
How do I _down_grade my smf install to 1.1.*?

I have seen several issues with the pretty urls mod when people change servers or move their install, maybe that issue could make the wiki faqs
These two really should not be documented, as neither are officially supported - There is no official "approved" way to downgrade, and we don't provide support for downgrading. And as always, mod support is to be kept to the mods own topic if possible, and Pretty URLs mod actually has a very good FAQ itself, that answers that question completely ;)
Finnish Support Local Moderator & Support Specialist
My Mods: Facebook and Twitter Sharer



Offline Illori

  • Doc Coordinator
  • SMF Master
  • *
  • Posts: 36,472
Re: User driven education
« Reply #11 on: January 13, 2011, 08:32:53 AM »
well even having an faq that states that we do not support it is a start ;), or in the pretty urls issue pointing people to their faq would help and could _possibly_ cut down on some support topics on that issue.

Offline Angelina Belle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,589
Re: User driven education
« Reply #12 on: January 13, 2011, 08:52:13 AM »
Lots of good ideas.

How about we get started on a nice QUEUE that doc helpers, doc team members, Community Support Helpers, Support Specialist, and even Dev Team members can all use to list "requests for documentation". As it gets completed, it can be moved to "fulfilled request for documentation"

Does this site provide any mods/utilities for maintaining to-do lists? Other than Mantis?
Should we have our own Mantis for this?

Or, since doc work is going on the wiki, should we just have a wiki page?

Who can start the wiki page?
Never attribute to malice that which is adequately explained by stupidity. -- Hanlon's Razor

Offline Aleksi "Lex" Kilpinen

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 15,430
  • Gender: Male
  • The Artist Formerly Known as LexArma
Re: User driven education
« Reply #13 on: January 13, 2011, 08:57:35 AM »
Most common way of doing to-do lists here, has been a new topic that just gets edited on the run...
Finnish Support Local Moderator & Support Specialist
My Mods: Facebook and Twitter Sharer



Offline Illori

  • Doc Coordinator
  • SMF Master
  • *
  • Posts: 36,472
Re: User driven education
« Reply #14 on: January 13, 2011, 08:59:03 AM »
or how about a to-do page on the wiki people can <s>strike</s> though as they make the pages?

Offline Aleksi "Lex" Kilpinen

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 15,430
  • Gender: Male
  • The Artist Formerly Known as LexArma
Re: User driven education
« Reply #15 on: January 13, 2011, 09:00:09 AM »
or how about a to-do page on the wiki people can <s>strike</s> though as they make the pages?
Basically the same thing, packaged a bit differently ;)
Finnish Support Local Moderator & Support Specialist
My Mods: Facebook and Twitter Sharer



Offline Angelina Belle

  • SMF Friend
  • SMF Hero
  • *
  • Posts: 7,589
Re: User driven education
« Reply #16 on: January 13, 2011, 09:18:29 AM »
Whatever it is, we have to get lots of other people to contribute to it.

Doc Helpers and Doc Writers should be taking material supplied by Support Specialiasts, Support Helpers, and Devs, and making it easy to understand and use.

So we should make it easy for them to deliver a big chunk of text to us, so we can apply the doc writing guidelines to it (grammar, spelling, naming conventions, etc), and give them back a link to the finished product.

To my mind, the wiki is a good place to do this, because we can add a new section to a page, and then remove a section after we complete the task, but never lose anything by accident because it is kept in the history.
Never attribute to malice that which is adequately explained by stupidity. -- Hanlon's Razor

Offline Joshua Dickerson

  • SMF Friend
  • SMF Super Hero
  • *
  • Posts: 12,666
  • Gender: Male
    • joshuaadickerson on LinkedIn
Re: User driven education
« Reply #17 on: January 13, 2011, 10:02:04 AM »
The reason it was in doc team board is because it directed at the doc team. I think I am going to start a small manual for us on the doc team. It will contain roles and stuff like this.
Need help? See the wiki. Want to help SMF? See the wiki!

Did you know you can help develop SMF? See us on Github.

How have you bettered the world today?