Difference between revisions of "FAQ backend guide"

Revision as of 04:38, 17 February 2009

When I first started thinking about how to write this, I tried to think of a way to make the LJ FAQ system make sense in a simple and elegant sort of way. Several days later, I concluded that this just wasn't possible. The FAQ system we'll be working with is a byzantine mess; there's just no getting around this. We will be getting a new system at some point, but for now, we're stuck with what we've got.

Privs

There are three privs that are relevant for documentation: faqedit, faqadd, and faqcat. They do pretty much exactly what you'd expect them to. Faqedit lets you edit existing FAQs, faqadd lets you add new FAQs and faqcat lets you create and delete FAQ categories.

On Dreamwidth, I'm going to be giving the whole userdoc team faqedit and faqadd privs, but won't be giving out faqcat. We won't need to be changing FAQ categories much, so I'll do that when it's needed. Be thankful: the faqcat system is even more messed up than the rest of the FAQ system, requires obnoxious console commands, and makes absolutely no sense.

/admin/faq/

The main page you'll be spending a lot of time on as you write and edit FAQs is /admin/faq/. On this page, there's an "add to FAQ" link at the top which is used to create a new FAQ, and then there's a list of the FAQs, which each one looking something like this:

[edit] (10) {2} How do I create an account?

The edit link is obvious, as is the name of the FAQ. The numbers slightly less so. The first number, in (parentheses), is the sort order. This determines what order the FAQs appear in within their category; the lower the number, the higher up the FAQ appears. The second number, in {braces} is the FAQ number. In this case, we're dealing with FAQ 2: http://www.dreamwidth.org/support/faqbrowse.bml?faqid=2. When a new FAQ is created, it's automatically given a number one higher than the last one created.

faqedit.bml

This is the page where you actually input the text of the FAQ you're writing. I'd recommend that you actually write the FAQ in a text editor and copy and paste it over to here. Especially before the site is officially launched, there's some possibility for instability, so it's better to have a copy of everything saved locally. Even after launch, it's better to be safe than sorry.

You reach faqedit.bml either by selecting to add a new FAQ, selecting to edit one of the existing ones, or by selecting "edit this FAQ" at the bottom of a FAQ page itself (eg http://www.dreamwidth.org/support/faqbrowse.bml?faqid=1). Obviously, if you're editing an existing FAQ, the fields will start off with the existing FAQ, whereas if you're making a new one, they'll be blank.

For each FAQ, there are currently 5 fields here: category, sort order, question, summary and answer. However, we're going to be getting rid of the answer/summary split. Once this gets done, we'll be down to just category, sort order, question and answer. These are pretty much what you'd expect them to be, but with a few notes and caveats.

• Answer. Markup here works the same way as it does in LJ entries. That is, line breaks will automatically be replaced with <br>, but you can add in other HTML as you please. One thing to look out for is that if you're using lists (<ol> or <ul>) this can lead to you ending up with a lot more whitespace than you wanted. To get around this, enclose the list in <lj-raw>...</lj-raw> tags.

• Category. As you'd expect, except that if the category is left blank, the FAQ will be "hidden". That is, it won't show up on /support/faq.bml or on /admin/faq/ but it will still exist, if you know its URL. This is generally preferable to deleting a FAQ entirely, since it will mean any links to the FAQ will still work (though obviously the FAQ also needs editing to reflect that it's no longer current information). We're also going to use this on Dreamwidth for our initial implementation of guides. I've created a knockup of a guide to show how this is going to work. Note that the FAQs linked to on the internal navigation for the guide don't show up on the main FAQ page. At the moment, if you want to create a hidden FAQ, you need to first create it in an existing category, and then edit it to remove its category. This is something else we're looking to change sooner rather than later.

• Sort order. Although it's not required, it's best to do sort orders as multiples of 10. That way, if you need to add a FAQ between the first and second in a category, you can just add one with sort number 15, rather than having to edit the whole category's sort numbers.

When editing a pre-existing FAQ, there's also a dropdown "select modification level for x" for question, summary and answer. This is to do with the translation system. Since we're not doing any translations, you can safely ignore this.

Expansion variables

Entering anything in [[ ]] below will expand it according to the list below. These come in handy for making FAQs "say the right thing" to users while reading them.

[[username]] - Replaced with the username of the person viewing the FAQ, or "username" if they aren't logged in.

[[journalurl]] - Replaced with http://[[username]].dreamwidth.org/

[[journalurl:dw_news]] - Replaced with http://dw-news.dreamwidth.org/ (you can obviously use any other username you want there.)

[[faqtitle:#]] - Replaced with the title of the FAQ in question, so to link to another FAQ, you can use <a href="lj://faq/#">[[faqtitle:#]]</a>.

[[gmlitem:code]] - Replaced with the content of the translation string referenced by "code". You can find the translation string for something on a page by adding ?uselang=debug to a page's URL, and then looking for a ".foo.bar" title where the text would otherwise be. Then, to make the "code" part of this tag, you put a slash and the page name, then the element name, e.g.: /pagename.bml.foo.bar.

You may want to use gmlitem to refer to stuff that you're writing now that the Site Copy team will edit later (i.e., when referring to the "Mutual Friends" option on /manage/profile; we aren't going to call it that in the final product, but I don't wait to write my FAQ, so I can use [[gmlitem:/manage/profile/index.bml.fn.mutualfriends]], which will say "Mutual Friends" right now, but will change to say whatever we call that option once the translation string is updated.). There are some cases where the heuristic I gave above isn't the right one, in which case you may want to look at this lj_userdoc post on LJ which details how to get the codes in more detail: http://community.livejournal.com/lj_userdoc/699462.html