Draft for specs of new FAQ system

[rho]

It took a little longer than I'd hoped, since my life is being busy right now, but this is the first draft of the specifications for the new FAQ system that we're going to write. At this point, please comment liberally. Consider this a call for feedback as much as anything else. How does the proposed system sound to you? Is there anything that I'm missing? Is there anything that sounds particularly awesome or desirable? Are there any bits that aren't clear?

DOCUMENTATION SYSTEM OVERHAUL

GOAL
To completely rewrite the documentation system from the bottom up, providing increased functionality for end users and better admin tools for site admins.

BACKGROUND
The FAQ system that we currently have on Dreamwidth is the one we inherited from LiveJournal, and it's showing it's age in a big way. As I understand it, the system was basically a quick hack that Brad wrote some time back in the year dot, and while it's received a few updates since then -- some from LJ and some from us -- it's still essentially the same old pig, only now it has lipstick on.

Rewriting the system from the bottom up will be a major development task but will be worth it in the long run as the time spent on it now is paid back later in ease of administration, increased ability for users to find what they're looking for, decreased workload for the support team, and so on.

The new system will include:

Increased searchability -- we want for users to be able to find what they're looking for easily and without headaches, with multiple possible routes through the workflow of finding the information, to suit different types of people.

Metadata -- Related to searchability concerns, the addition of metadata such as related documents, keywords, etc. will increase usability.

Accessibility concerns -- since we're redesigning from the bottom up, we can plan for accessibility from the start rather than trying to shoehorn it in at a later date.

Version control -- The addition of version control will make the FAQ system easier to manage and update, and will also provide a failsafe in case of accidental (or malicious) deletion.

SKILLSETS REQUIRED
Backend Engineering
Frontend Engineering
Human Interface Design

REQUIREMENTS

The requirements here are split into three main parts. While the exact delineation of the split is somewhat arbitrary, having it split up helps to keep the size of the lists more manageable and therefore easier to read.

PART I: ANATOMY OF THE FAQ

This section covers the data and metadata that will make up the FAQ.

Must:
Include the title/question
Include the main body/answer
Include short-version titles, which would be used in human-readable URLs
Include categories. Any FAQ can appear in any number of categories.

Should:
Include keywords. These would be used to aid in searching, for instance by providing synonyms.
Include FAQ numbers for backwards compatibility. FAQ number URLs should forward to new canonical versions.
Include a "related FAQs" section.
Include limited MediaWiki-style markup. Specifically:
* lists
==headings== and ===subheadings===. These should give appropriate styling, and should also generate in page anchors and (where appropriate) a table of contents.
[[quick links]]. These should work off the short version titles. Default link text should be the long title of the linked FAQ (or a translation string with the FAQ title passed to it) but should also use pipes for changing link text, as per MediaWiki. May be formatted as [[faq:quick link]] instead to avoid collisions with existing FAQ markup. Should also include title attribute in the <a> tag.
Include all the functionality currently available as FAQ variables: http://wiki.dwscoalition.org/notes/FAQ_variables

[Author's note: we might want to spend some time making sure we get this markup done right, because this is something that I think would be awesome to expand across the site at a future date. It would be awesome if I could give short titles to entries and then link to them with [[rho: entry title|my awesome entry]] or similar. If we want to do that, we want to make sure we get the formatting right from the off.]


Could:
Allow nested categories.


PART II: THE USER EXPERIENCE

This section covers what the user will see when they look at the FAQ.

Must:
Have a robust FAQ search. This would search keywords, long title, and main body. It would also spit out categories that fit the search criteria as well.
Allow the user to choose a category and then see all FAQs in that category.
Allow the user to choose a category and then see a list of all FAQs in the category.
Allow the user to see a full list of all FAQs, similar to the current faq.bml
Show creative commons information on each page.

Should:
Show the related FAQs (see above meta-data) to the user ("This not what you're looking for? How about these?")

Could:
Allow multiple viewing options for FAQs with subheadings. For instance, they could be viewed paginated, as we have current guides (eg http://www.dreamwidth.org/support/faqbrowse?faqid=31) or could have everything on a single page.
Allow boolean searching.

Would be nice:
Have an API for interacting with the FAQ so people could make interesting FAQ-based widgets.
Have a wizard to direct people who aren't sure what they're looking for to where they need to be.


PART III: THE ADMIN BACK-END

This section covers the back-end of how the FAQ gets updated and maintained.

Must:
Include version control. In addition to the current version of the FAQ, we should also keep records of all previous versions.
Include a "patch" system, whereby any registered user can create a patch to change any part of a FAQ (exceptions: number, short title), which must then be reviewed/committed by a user who has appropriate privs.
Allow comments to be made on any pending patch.

Should:
Have separate privs for the following:
Viewing pending patches.
Commenting on pending patches.
Viewing comments on patches.
Committing patches.
Allow all privs to be set either globally or by category.
Make it possible to sysban someone from the FAQ admin back-end in case of abuse.

Could:
Allow patches created in the system to be exported so they could be, for instance, uploaded to a zilla items and then stuck back into the system.
Also create a priv for creating a patch in the first place. This isn't something that I want for us, since I want to make the hurdles to contributing as low as possible. It may be useful for other sites though, or for us-in-the-future.

[Author's note: I'm not sure how my desire to make it as easy as possible for people to contribute will fit with the way Dreamwidth is handling contributor licensing. Someone more knowledgeable than me about the legal ramifications can figure that one out.]

PART IV: MISCELLANEOUS

This section covers the odds and ends that don't fit anywhere else.

Must:
Import all currently existing FAQs over to the new system.
Play nicely with support. I'm not going to include how any of these changes would interact with support here, since that's probably an issue that's better handled by the people currently on the support team. Issues like in-faq anchors and FAQs belonging to multiple categories would need to be considered though.
Have accessibility concerns prioritised. I have no clue what we'd need to do here, and will seek feedback from the accessibility team.

Should:
Have a nice way for people to take our FAQs and put them onto their own DW site.

Would be nice:
I'd like if we had nice information about popular FAQ searches, popular FAQs, which FAQs were getting linked in support most, which FAQs linked in support led to highest percentage of reopened tickets, which had the highest task completion rates, which FAQs had a lot of "related FAQs" linked followed, and so on.

POTENTIAL PROBLEMS
The big difficulty I can envision here is trying to make sure that the new FAQ system plays nice with the translation system (die die die). This is a problem because anything that involves the translation system (die die die) is automatically a problem by definition. I don't actually understand the translation system (die die die) well enough to see the pitfalls or suggest ways around them, since I haven't yet had my mind turned to slush by Great Cthulhu.

PS Sorry for the formatting. I wrote this up as a text document, so some formatting is lost here.

Comments

[cesy]

It all sounds pretty good to me on a first read-through.

[katieastrophe]

Looks good.

Suggestion for making FAQs easy to find: a tagging system? May be redundant with search facility but figured there's no harm in suggesting it...

[rho]

Having multiple categories for each FAQ will behave a lot like tags would. Since we'll not be limited to one category fr each FAQ, we'll be able to have a broader range of categories, I think.

[katieastrophe]

Good point, ignore me then ~_^

[sophie]

However the FAQ system plays with the translation system (die die die), we should do it in such a way that the admin-facing parts do *not* use anything specific to the translation system (die die die) as it stands right now, as it'll be redone.

In other words, from an FAQ admin's point of view, it should be as easy to work with the current translation system (die die die) as it would be for any future, rewritten version.

[pauamma]

Right now, the main interface (besides the translation strings in the admin pages themselves) is the use of FAQ variables (or whatever will replace them) to quote UI strings. What may happen when the translation system (may it die painfully a thousand times over) is replaced with something sanity-inducing is that the names used to refer to the strings will likely change, but dealing with that would be a sitewide effort, not just for the FAQs.

[azurelunatic]

For accessibility, should the FAQ pages obey ?style=mine?

[jesse_the_k]

Yes, please! (Large print user.)

[zarhooie]

It looks good to me. :)

Sticky Posts

[highlander_ii]

I wasn't sure how else to notify the docs team, so this seemed the best course of action:

* Sticky posts - how to make them, what they are, etc, needs to be added to the FAQs.

I assume this is on the list of 'things to do', but in case my assumption is wrong. =)