Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Pages: 1
[wiki] FAQs Translation/Management
(An oft returned-to topic, so it’s getting it’s own thread.)
TxB has been used for some time now as a platform for translating the FAQs. The original approach was to create this index list (which at the time mimicked the one at .com), and then let translators begin with the index and then the individual faq pages. Though efforts have begun in 3 languages, progress has been glacial, and the unorthodox index page in the wiki is one likely reason (just one). The long, static index page is a big drawback, not only for wiki authors/editors who would have to maintain it, but also for translators who must localize it (a great deal of work). In fact, that page is simply unnecessary in the wiki. We could use wiki functionality to improve that considerably, just like we’re doing with tags.
First, we could employ a custom namespace that each faq article title is prefixed with, regardless of language: faq:. This keeps FAQ pages away from normal docs, which is useful for wiki maintenance and group rights management, but it’s also a great way to immediately identify a FAQ article from otherwise, thus inherently permits more concise FAQ titles. In other words, if a title is prefixed with “faq:” the reader immediately knows that and there’s no need to use “How do I…” “What is the…”, “Where can I…”, etc. which is just title cruft anyway. A title like How do I create a MySQL database? simply becomes faq:Creating a MySQL Database (question marks dropped). The latter is considerably more usable (concise and direct in meaning).
Next, we could make use of wiki categories to group FAQs by their sub-categorical topics. You’ll note that the current FAQ index at .com has changed since the one in the wiki was started, and understandably no one has bothered trying to keep up with that in the wiki. With wiki categories, it’s not necessary to make labor-intensive edits to the long index lists; you simply maintain the FAQ articles themselves and sub-categorize them automatically with category tags — no more long, static lists at all!!
If we use the existing FAQ structure at .com, we can imagine browsable organization like this:
- category:FAQs
- category:Acquisition and Installation
- faq:Creating a MySQL Database
- faq:See Textpattern in Action
- faq:System requirements
- etc.
- category:Development
- faq:Reporting Security Issues
- faq:Notice: undefined variable.. and similar messages
- etc.
- category:Diagnostics
- faq:The following PHP functions… are disabled
- faq:Clean URL Test Failed
- etc.
- category:Etc.
- category:Acquisition and Installation
This structure now exists in the wiki, though there’s many FAQs to add and categories to yet create. Now, should new FAQ subcategories arise, you simply adjust the category tag assignments at the bottom of a given FAQ article. You can even put a given FAQ article into multiple categories as needed. The English pages are simply placeholders with a link to the .com FAQ equivalent; their existence makes it easier now for translators to mirror a link against something meaningful in the wiki. It also makes it possible to begin drafting/managing English FAQs directly in the wiki should that ever be desired (and with some user group mods to restrict English versions, entirely feasible).
Instructions for adding English pages and translating FAQs are available from the main FAQs category intro. Translations already done for any FAQs will be transferred accordingly and the old translation index will be deleted.
Last edited by Destry (2008-11-06 13:21:01)
Offline
Re: [wiki] FAQs Translation/Management
Forgot to mention something I’ve recently learned by chance while troubleshooting a different issue. The clever observer may have noticed already.
By default, MediaWiki categorizes articles alphabetically by first letter of article title. When articles are in a custom namespace, like “faq:”, that could normally be a problem because under the default behavior everything goes under “f” (for “faq:”), which does no good.
As it turns out, however, you can easily override this when adding the category tag by using a letter (a to z) to indicate how the title should be alphabetized. For example, while any page beginning with “faq:” would be filed under “f” when using [[category:FAQs]], we could easily file it under “u” by using [[category:FAQs|u]], which might be reasonable if the page was faq:Verifying Correct Upgrades (presumably influenced by the notion of “upgrades”).
Slick and easy!
Ed. Oops, correction on those code examples.
Ed. 2 For those wondering why such a link syntax does not make the link appear as u like it would if used as an inline text link, it’s because the category tag is not in normal link context. To do do that (which you wouldn’t do in this case anyway) you would add a colon before “category:”, [[:category:FAQs|u]], which would result in a link showing as “u” going to the FAQs category index. The faq page itself would thus not even be categorized at all.
Last edited by Destry (2008-11-06 13:55:10)
Offline
Re: [wiki] FAQs Translation/Management
Translators,
Probably the first thing you should do with regard to translating the FAQs, is translate these two instructions in the discussion page of your respective FAQ category indexes.
For example:
- Spanish would translate them in category_talk:Preguntas Frecuentes
- Italian in category_talk:Domande Frequenti
And so forth. Adjust the instructions as needed.
Remember to add links to the instructions from the main category page so they are easily found, as shown in the English category intro here.
Offline
Pages: 1