[wiki] Have FAQs had their day?

Bloke · 2009-10-07 13:51:57

Something’s always bothered me about our FAQs on textpattern.com. Some of them are actually frequently asked and could be argued to be useful; some not so — seriously, who wants to know how to open links in a new window to be told to use the zem_prblock plugin?

I had a chat recently with Destry about this and both our thoughts are that the existing FAQs on textpattern.com are not doing their job. We’re not alone

For starters, there are waaaay too many FAQs. Plus they’re locked down so only the devs can write/alter them. This is a load on us that we probably shouldn’t carry. Now that Textbook has started to really come of age thanks to an increased volume of awesome contributors I’d argue that if there are any true nuggets of usefulness in the existing FAQs they be moved to their own section in the wiki. Even better, make some new wiki articles and roll some of the more related FAQ topics together into a series of mini how-tos or tutorials and abolish the FAQ altogether. This kind of thing has been discussed way back in ’05 and Textbook moved a long way towards being what it is now thanks to Destry and some keen enthusiasts. Perhaps now is the time to step it up a gear once more.

The original argument has always been that the FAQs should be “correct” and exactly mimic the core, which only the devs know well enough to document. Well some of the FAQs are out of date now and a tonne of them are nothing to do with the core (per se) anyway. There are so many, that it’s a chore for a handful (3) to have to go through them and edit/delete them or hope someone else spots something erroneous, and tells us. imo, it’s far better for the community to be able to keep any FAQs up to date — if they’re needed at all.

Certainly some FAQs are not even that. ‘How to submit a tag trace’ is one of the most common linked items to help newcomers allow those more experienced to help track down problems. It’s not exactly ‘frequently asked’ because nobody new here knows to ask! So is it far better to have a Troubleshooting document on the wiki that reflects a series of steps one can go through with common things in it (e.g. how to look at / read / post a tag trace; check your tags are closed properly; check for dangling txp:else tags; and so on)?

If this kind of thing is acceptable I’d rally for having the textpattern.com FAQs closed for good. Any link to textpattern.com/faq should be redirected to somewhere on textpattern.net and / or pass the words in the FAQ title to textbook as search criteria. Perhaps the odd really really useful FAQ could be maintained in the wiki or rolled into a common article as described above and have a dedicated redirect from textpattern.com/faq/whatever? I’d guess the stuff about the TXP licence, system requirements, and so on should become a regular article on textpattern.com and not a series of disparate FAQ entries.

As a side note this means that the top navigation bar in the new v2 site will have a link directly to Textbook instead of to the existing FAQs, which makes a lot of sense given that the masthead is going to be standardised across the 3 or 4 domains we own.

So who’s with me? Or who thinks it’s a stupid idea? Anyone have any better suggestions? And if we do it, who’s going to help me pull out the good stuff from the FAQs and translate it to some wiki documentation and organise it into something that everyone can benefit from?

Thanks in advance for any contributions to this topic. You all rock.

Gocom · 2009-10-07 14:04:10

Good idea. Plus, cut the “Tag Trace 1o1 how to” into smaller list that grunts understand.

Grunt think book bad, booz good. Grunt no read. Grunt fight, grunt shoot... eh.

jsoo · 2009-10-07 14:51:20

Agreed that the current FAQ list is not as useful as an FAQ list should be.

Agreed that a “Troubleshooting” section on TextBook is needed.

Looking for the FAQ list is a very common reflex for new users. I think there ought to be something named “FAQs”. Agreed that it should actually represent FAQs!

colak · 2009-10-08 06:58:46

I agree that FAQs should go to the textbook whereas any FAQs on the site should target non txp users and these should be of general rather than troubleshooting nature.

As such I think the following topics could and it would probably be more appropriate to remain in the .com site

Acquisition and Installation
Features and Limitations
Forum
Licensing

Last edited by colak (2009-10-08 06:59:28)

colak · 2009-10-08 07:01:46

still on topic: I think that with the current release featuring multi site support this should be updated.

Last edited by colak (2009-10-08 07:02:31)

Destry · 2009-10-08 09:52:47

BIG thanks to Stef for 1) bringing this forward, 2) mentioning that link in the content strategists group because you’re not going to find more knowledgeable people on content handling than you will there, and 3) digging up one of my passionate gripes from years past. <g> It’s amazing it takes five years (to the month) before the clouds part. One can only wonder where TextBook would be if history had been a little different. And back then I was only talking about .com and .org, not all the other rogue documentation projects that sprout up periodically out in the bush that add to the decentralization of help.

But history doesn’t matter now, and I don’t want to argue the merits of a community working together instead of as soloists in the name of community, which is not the same thing. Better to focus on this opportunity Stef has forged none too late.

Why none too late? Because in the new .com design, the main “Documentation” link goes to the glorified FAQs, and a link to TextBook is buried out of site — literally! To call FAQs “documentation” is extreme, if not downright silly. Do you call the customer support guy on the telephone documentation? It makes about as much sense. The content pros would tell you that if you even need FAQs, you are probably doing things wrong if you have more than 15. FREQUENTLY. ASKED. QUESTIONS. Not every question that has ever been asked.

FAQs can certainly—and quite easily—be converted into documentation, and Stef has touched on some ideas. Here’s some more thoughts towards that end to help get the ball moving quickly so that the long awaited .com redesign can be realized.

Immediate objective should be to FIX the IA of the new site navigation. There likely multiple problems there, but the current issue is about the “Documentation” link, which should point to the wiki, and sensibly at docs.textpattern.com (with aide of some restructuring on .net side and a redirect on the .com side)

Next is the question of how to save, move and rewrite the FAQs from .com. I don’t think there’s an issue with saving; they’re Txp articles currently, so secured in that way. I would say that moving them in their current form would be the best way to move them quickly, which also eliminates any undue holdup on launching .com. We can always “process” them in the wiki afterwards more appropriately. There’s already an FAQs Index in the wiki that was intended for localization efforts (which was another user consideration the .com FAQs never took into account). This can easily be updated and used to quickly copy/paste articles over; each FAQ having it’s own wiki page, just to ensure we have a wiki carbon copy of the .com version to start with. Before creating those English pages, it might be worth considering whether we need a “faq:” namespace in the wiki so all those pages are not clogging up the normal docs pages in All Pages; it just depends if all the individual FAQ pages would be kept or not. The logic would suggest not, at least not as they are written (volume of pages), so perhaps it’s better mimic their organization using wiki categories and then removing the pages later as their content is rewritten (thus redundancy removed).

Finally, I alluded to the idea of processing or rewriting the FAQs, and all that means, like Stef suggested, is putting individual FAQ content in context of the documentation that already exists and then removing the redundant copy. Where copy needs to be used in more than one location, it might be wise to use a wiki “template” (equivalent in function to a php include, or Txp form) so that when it’s updated, it’s updated in one file and propagates everywhere.

We could also make the case that where content should remain in .com (e.g., features, licensing…) that information be removed in the wiki (again for the sake of removing redundancy where it’s can’t be managed via a single file) and simply put a link to the .com article in those instances.

In other news, I’ll be jumping into the wiki presentation again soon to bring the theme into alignment with the new .com design, and hopefully the .com IA will adopt the kind of navigation the wiki suggests for a more holistic user experience across the family of sites.

—-

(A few edits for the sake of peace-keeping.)

Last edited by Destry (2009-10-08 11:18:08)

Bloke · 2009-10-14 12:38:18

Since there’s been no vehement backlash to this idea I’ve gone ahead and started the process of adding a Troubleshooting category to Textbook. The idea is that this category will replace any links to textpattern.com/faq.

There is a subcategory ‘FAQ’ but that’s purely for actual frequently asked forum questions or things that people often find themselves doing. Currently there’s only one (how to reset your password via phpMyAdmin) but there will be a few more as we find them. This category should never exceed 10 or 15 items. If it does, it’s time to consolidate the questions into some articles elsewhere.

The stuff about system requirements, TXP’s licence, contributors, patrons, languages, etc should all point at the txp.com site. As you come across such content, please mark it for deletion so we can easily find it and replace it with the following links when the new site goes live:

System requirements: http://textpattern.com/about/119/system-requirements
License: http://textpattern.com/license
Contributors: http://textpattern.com/contributors
Patrons: http://textpattern.com/patrons
Features: http://textpattern.com/features
Supported languages: http://textpattern.com/features/301/languages

There are currently 3 subcategories in the Troubleshooting section, though I’m not sure they’re appropriately named yet:

FAQ : true Frequently Asked Questions
Unexpected behaviour : Any time someone scratches their head because they don’t see what they expect
Errors, Warnings and Notices : any info regarding specific types of error message that people are seeing, e.g. “article tags can only occur in an article context”. Perhaps there should be a link to the troubleshooting stuff on the Diganostics tab in here too? Any good ideas on how to organize this?

If anyone has any better ideas, please make it so.

I’ve started to go through the txp.com FAQs, ignored questions that plainly aren’t frequently asked, nor are of much value and have begun to compile the more useful ones into actual articles in the Troubleshooting category, or incorporate the stuff in other articles. This is only at the very pupae stages; any and all help greatly appreciated. Keep an eye on the contribution scores wiki page (click contribs) to see who’s done what so we don’t duplicate effort.

Many thanks for any help in this task.

Last edited by Bloke (2009-10-14 12:40:53)

els · 2009-10-14 13:57:26

Nice work :)

A couple of thoughts:

There already is a category FAQs. The pages in that category only contain links to the .com site faqs. Not sure why it is there, probably just to facilitate their translations, but I don’t see much reason to keep it?

The menu on the left should be updated. The link to the current category FAQs could be replaced with a link to your category Troubleshooting I guess. (Edit: Added link to Troubleshooting and left the link to FAQs for the moment. I think it can be removed once we’ve matched the existing translations to the new FAQ pages? Or do I overlook something?)

Duplicate/confusing(?) content: your page Forgotten password now exists next to Resetting Admin Password. Those two could be integrated I think. The older page contains instructions how to do it using phpMyAdmin’s UI which is a useful addition for those that are not so comfortable using command line and queries. Also the MySQL queries differ a bit in both articles, my MySQL knowledge isn’t very good so for me that is confusing…

Structure: the Resetting Admin Password page is now under Tutorials. I’d rather categorize it under Troubleshooting, like you did with your new page. Would it be useful if we came up with some guidelines as to what belongs where, and add them to the Category_talk pages?

Last edited by els (2009-10-14 14:06:54)

Bloke · 2009-10-14 14:20:40

Els wrote:

There already is a category FAQs… I don’t see much reason to keep it?

Me neither. I think Destry said it was for translation efforts but it’s not used. It can be marked for deletion I think.

Thanks for editing the left hand menu. I couldn’t find the right template for it so just added the Troubleshooting to the ‘Orientation’ under ‘Features and Capabilities’ so I could get to it. It needn’t be in both places so I’ll remove it from the Orientation list.

your page Forgotten password page now exists next to Resetting Admin Password. Those two could be integrated I think.

Quite right, well spotted. The GUI stuff in the latter link is very useful, as you say. Resetting Admin Password is linked from a few places. Like you say, it’s just a case of working out where it best fits.

Would it be useful if we came up with some guidelines as to what belongs where, and add them to the Category_talk pages?

Very. Good idea.

els · 2009-10-14 17:09:37

Bloke wrote:

Resetting Admin Password is linked from a few places.

Oh dear. I don’t want to hijack your thread, but following that link – and beyond – leads to lots of old pages that can only be found by accident (like I did now), and that should (in my opinion) be removed as soon as possible…
I’m also still trying to clean up the Translations links on the right, on a lot of pages more often than not they lead to non-existing pages.
Pff… it’s hard to keep a clear overview of what can stay and what should go, and if it can stay where should it go, and so on…

BTW, what do you mean when you say ‘mark for deletion’? I can’t find an option to do exactly that.

Bloke · 2009-10-14 17:21:42

Els wrote:

following that link – and beyond – leads to lots of old pages that can only be found by accident

Yes, I’ve discovered all sorts of stuff like that. If it looks truly outdated or has been rolled into something newer I’ve been tagging the page with {{Stop}} so at least it makes it obvious its old. But I’m sure very few will miss stuff like that if it’s deleted outright… right?!

I’m also still trying to clean up the Translations links on the right

Yes, that’s a minefield too. Eegads!

BTW, what do you mean when you say ‘mark for deletion’?

Sorry, I’m having one of those weeks… too much Internet is robbing my brain of vital dictionary neurons! I kind of meant to use {{Stop}} if it’s a whole page or if it’s just a link or something, put some text nearby that we can search for later (e.g. TOREMOVE). It won’t be there long. I’m not sure if putting such words inside HTML comments can still be searched — if so, all the better. Just means that when the new site goes live we can do a quick search to find all the stuff we need to change.

Alternatively, I spose you could copy the URL of any pages that need changing and stick ‘em in a text document for later perusal?

Last edited by Bloke (2009-10-14 17:22:56)

els · 2009-10-14 22:11:08

Bloke wrote:

I kind of meant to use {{Stop}} if it’s a whole page or if it’s just a link or something, put some text nearby that we can search for later (e.g. TOREMOVE). It won’t be there long. I’m not sure if putting such words inside HTML comments can still be searched — if so, all the better. Just means that when the new site goes live we can do a quick search to find all the stuff we need to change.

Alternatively, I spose you could copy the URL of any pages that need changing and stick ‘em in a text document for later perusal?

I started a list on my User_talk page, but it turns out to be much easier :)

Textpattern CMS

Textpattern CMS support forum

#1 2009-10-07 13:51:57

[wiki] Have FAQs had their day?

#2 2009-10-07 14:04:10

Re: [wiki] Have FAQs had their day?

#3 2009-10-07 14:51:20

Re: [wiki] Have FAQs had their day?

#4 2009-10-08 06:58:46

Re: [wiki] Have FAQs had their day?

#5 2009-10-08 07:01:46

Re: [wiki] Have FAQs had their day?

#6 2009-10-08 09:52:47

Re: [wiki] Have FAQs had their day?

#7 2009-10-14 12:38:18

Re: [wiki] Have FAQs had their day?

#8 2009-10-14 13:57:26

Re: [wiki] Have FAQs had their day?

#9 2009-10-14 14:20:40

Re: [wiki] Have FAQs had their day?

#10 2009-10-14 17:09:37

Re: [wiki] Have FAQs had their day?

#11 2009-10-14 17:21:42

Re: [wiki] Have FAQs had their day?

#12 2009-10-14 22:11:08

Re: [wiki] Have FAQs had their day?

Board footer