FAQ improvement

Talk about Documentation
1

I made an attempt to improve the FAQ: https://openwrt.org/playground/faq/start

Concept

  • one faq -> one page
  • all faq pages in one namespace, no subnamespaces needed
  • structuring / filtering is done via tags

Advantages

  • easy creation of new faq pages, without bothering in which namespace to sort this faq into
  • usage of namespace templates which provide a basis for a new page instead of a blank page (login, create a testpage and see yourself)
  • easy structuring via adding tags
  • one faq can have multiple tags, showing up at multiple tag pages
  • in addition to the faq overview page, faqs can also be found by normal wiki search. Try yourself and search for: "satisfy", "error", "4MB", ...
  • one faq per page has a cleaner appearance than the previous "all faqs on one page". For comparison two current faq pages:
    https://openwrt.org/faq/before_installation
    https://openwrt.org/faq/after_installation
  • one faq per page allows for direct adressing instead of page#section adressing. Changes on the pagename are automatically adapted in the whole wiki, but changes on section naming are not, thus easily breaking links.

What do you think about this concept?

  • Good idea, and already perfect as is!
  • Good idea, but needs some improvements.
  • Bad idea, the current concept is better.

0 voters

1 Like
2

I forgot to mention: Apart from voting, you can of course also leave comments regarding good/bad things in the old and new FAQ concept.

3

It should have easily accessible, "static links" somehow so that when someone links in the forum to a specific topic in the FAQ, someone a week, month, or year later gets to the right topic.

4

Thanks for your feedback!

The new concept does have static links, e.g.
https://openwrt.org/playground/faq/cannot_satisfy_dependencies

1 Like
5

Not that much feedback within the last 2 weeks, only 5 votes, but still enough to see a trend: 80% positive feedback.

Based on this, I will work further on this proposal and implement it for productive use during the next 2..4 weeks.

Further feedback and suggestions are welcome!

6

Although with some delay, the new FAQ has been implemented now.

We now need some FAQ rules.

My first DRAFT proposal:

  • What is a FAQ?
    • An FAQ is a list of frequently asked questions (FAQs) and answers on a particular topic
    • Used in [...] online forums where common questions tend to recur
    • The purpose of an FAQ is generally to provide information on frequent questions or concerns.
  • FAQ pages shall not be a replacement for existing wiki pages. Instead, they shall serve as easy to find stepping stones which give short explanations + solutions and direct users to highly related, already existing and detailed documentation in the wiki.
  • FAQ pages may contain excerpts from existing pages, but shall not contain a complete copy of those pages. In case a complete copy would be needed, please just link to the existing wiki page instead of copying.
  • When to create a new FAQ?
    • Questions often seen in the forum
    • You have the question AND the answer available
    • You have discussed your proposal for a new FAQ in the OpenWrt forum
  • When not to create a new FAQ?
    • You have a question, but you do not know the answer. Use the OpenWrt forum to get answers to your unsolved problems.
  • What to put into a FAQ page
    • SHORT and structured info about the issue (what’s the problem?)
    • Circumstances under which the issue occurs
    • Steps to reproduce
    • Symptoms
    • Root cause
    • Solutions
    • Links to already existing wiki pages
    • Links to helpful forum discussions
  • What not to put into a FAQ page
    • Several pages long explanations (keep it short!)
    • Complete copies of other wiki pages
  • Discuss your proposal for a new FAQ in the OpenWrt forum before creating a new FAQ page

Your comments are welcome!

1 Like