HackerOne users: Testing against this community violates our program's Terms of Service and will result in your bounty being denied.
Please upgrade here. These earlier versions are no longer being updated and have security issues.

River's problem with the ToC in the FAQ

This discussion was created from comments split from: Category accordion for version 2.3.
River

Comments

  • whu606whu606 I'm not a SuperHero; I just like wearing tights... MVP
    edited December 2016

    @River said:
    since you are new to forum. I'll re-gift this to you https://vanillaforums.org/discussion/28420/frequently-asked-questions (avoid the table of contents the links don't take you to the questions in the faq and some questions in the faq are missing in the toc).

    @River

    As often before, you point out a fault, but don't offer a solution.

    Here's the thing:

    I'm more than happy to edit the ToC and the FAQ thread.

    You're more than happy to point out the ToC/FAQ is sub-optimal, and you know why, but you can't be arsed to share what you know, you'd rather just point out a failing.

    So, you know what needs to be fixed, but are not prepared to do anything to facilitate that.

    Wouldn't it have been as easy, and certainly more useful for users, if you had shared what you had found as wrong?

    Linc
  • RiverRiver MVP
    edited December 2016

    @whu606 said:
    @River

    As often before, you point out a fault, but don't offer a solution.

    SOLUTION:

    probably the best solution is to remove the TOC if inability for TOC to be corrected.

    BETTER SOLUTION:

    otherwise click on a link, if it doesn't go to the question in the FAQ it is not a TOC for the FAQ

    also a TOC looks like this.

    1 - question 1 Title of Question 1 (link to question 1)
    2 - question 2 Title of Question 2 (link to question 2)
    3 - question 3 Title of Question 3 (link to question 3)
    etc.

    its really quite simple.

    if there are 30 question in FAQ - it should have 30 items in TOC, if more more, if less less.

    the TOC should reference items (questions in FAQ) not shoot out of the FAQ. That way people stay in the fAQ to get an idea of all info available.

    Pragmatism is all I have to offer. Avoiding the sidelines and providing centerline pro-tips.

  • whu606whu606 I'm not a SuperHero; I just like wearing tights... MVP
    edited December 2016

    Alternative solution 2

    Draw up a ToC yourself, and I'll edit the post.

    Alternative solution 3

    Any time you come on a link that doesn't work, let me know.

    Anything you think is missing, let me know.

    It's really quite simple.

    Or you could just keep standing on the sidelines telling everyone else how rubbish they are.

    It baffles me that you take the time to find stuff that is wrong, but not the time to help to make it right, but each to their own, I guess.

    Linc
  • RiverRiver MVP
    edited December 2016

    @whu606 said: but each to their own, I guess.

    @River said:

    @whu606 said:
    @River

    As often before, you point out a fault, but don't offer a solution.

    SOLUTION:

    probably the best solution is to remove the TOC if inability for TOC to be corrected.

    BETTER SOLUTION:

    otherwise click on a link, if it doesn't go to the question in the FAQ it is not a TOC for the FAQ

    also a TOC looks like this.

    1 - question 1 Title of Question 1 (link to question 1)
    2 - question 2 Title of Question 2 (link to question 2)
    3 - question 3 Title of Question 3 (link to question 3)
    etc.

    its really quite simple.

    if there are 30 question in FAQ - it should have 30 items in TOC, if more more, if less less.

    the TOC should reference items (questions in FAQ) not shoot out of the FAQ. That way people stay in the fAQ to get an idea of all info available.

    I guess I didn't explain this too well. Here are my suggestions. In most of the english-speaking world a Table of Contents is ordered sequentially, no randomly. That is what I was suggesting as well as having the title link go to the question. Yes the first 4 questions are a bit oddly ordered due to editing limitations.
    Easy-peasy to see and should be easy -peasy for you to follow. I provide the fishing rod, if you are up for the changes and for future TOC's

    e.g.

    1 How do I change the timezone from utc to a different timezone for users who are not logged in (Guests)?

    2 How do I make the yellow icon for "new" discussions appear?

    3 Clicking on a discussion returns a blank page after a fresh install?

    4 How can I translate certain words or change wording?

    5 How do I create a config/locale.php if I don't have one?

    ... and so on for questions 6 -28.
    ....
    ....

    29 What are some basic troubleshooting steps?

    30 Addendum to troubleshooting steps for item 29.

    I'll beleive you at your word that you will edit accordingly.

    Pragmatism is all I have to offer. Avoiding the sidelines and providing centerline pro-tips.

  • whu606whu606 I'm not a SuperHero; I just like wearing tights... MVP
    edited December 2016

    @River

    The links all go to the comment they are meant to be linked to, so I don't know what your problem is there.

    I have added some links to comments that had been omitted. I have not added a link to the default roles as it refers to 2.1. If you or someone else wants to update it for 2.3, I'll add it.

    Now that you have clarified, the idea that the ToC should slavishly follow chronological order, in this particular circumstance, strikes me as ridiculous.

    Any FAQ on Vanilla that doesn't have 'Something has gone wrong' at the top is pointless, imo.

  • RiverRiver MVP
    edited December 2016

    whu606 said: I have added some links to comments that had been omitted.

    thats an improvement. but it could be better if you adhered to standards instead of implementing your own at your own whim.

    As you can see by not ordering the questions sequentially and numbering them in the TOC to match the numbers in the corpus of the FAQ - which is prone to ommissions and mistakes. As you have done and admit to.

    I guess the reason why there is a logical sequential structure to a Table of Contents thoughout the world (that you choose not to follow) is so it is easier for the maintainer NOT to make mistakes or unnecessary omissions because of inconsistent ordering.

    When there is a one-to one correspondenc between TOC question in sequential order these types of problems would be easier to find and fix and you wouldn't have so much trouble finding the problem when it is pointed out to you.

    you have freighted your sentence with the word "slavishly" as if following the Standard English language usage and application of a Table of Contents is bad. Perhaps you don't believe in Global Warming either.

    sometimes the last chapter in a book is the best, I have never seen an editor or an English teacher with adequate training use random order and put the last chapter of a book or paper or Faq as the first item in a Table of Contents. Because it make no sense, is difficult to follow, and it hard to read.

    The numbers in the questions would help as I tried to illustrate to you. Then it would be easier to view the TOC and refer a person to a particular question number.

    I guess the reason why there is a logical sequential structure to a Table of Contents thought the world that you choose not to follow is so it is easier for the maintainer NOT to make mistakes or unnecessary omissions.

    there are many ways to have things stand out, and still maintain sequential order

    I'll provide you with an example.

    with color , font size , or font strength or * or IMPORTANT or duplication of an important question at top. in addition to the complete list.

    e.g.

    1 How do I change the timezone from utc to a different timezone for users who are not logged in (Guests)?

    2 How do I make the yellow icon for "new" discussions appear?

    3 Clicking on a discussion returns a blank page after a fresh install?

    IMPORTANT 4 How can I translate certain words or change wording?

    5 How do I create a config/locale.php if I don't have one?


    you could also do something like this

    What do I do if I see the image below that states "Something Has gone wrong".

    1 How do I change the timezone from utc to a different timezone for users who are not logged in (Guests)?

    2 How do I make the yellow icon for "new" discussions appear?

    3 Clicking on a discussion returns a blank page after a fresh install?

    4 How can I translate certain words or change wording?

    5 How do I create a config/locale.php if I don't have one?

    .... 5 thru 14

    ....

    15. What do I do if I see the image below that states "Something Has gone wrong".


    or

    IMPORTANT: 15. What do I do if I see the image below that states "Something Has gone wrong".

    or

    15. What do I do if I see the image below that states "Something Has gone wrong".

    15. What do I do if I see the image below that states "Something Has gone wrong".

    or

    15. What do I do if I see the image below that states "Something Has gone wrong".")

    If you don't catch what I am saying - simply put you can still "SLAVISHLY" conform to TOC structure like the rest of the world (sequentially) and you could have numbers in TOC for questions and improve things with either duplication of your loved question "15 What do I do if I see the image below that states "Something Has gone wrong". "

    But I am through with this and you. I've have tried to educate you to improve things and conform to the world's view of a TOC. you can iyoo - in your own opinion do what you need to do and renege on your offer to follow my suggestions out of a decision to break with conformity.

    you will also note that: What do I do if I see the image below that states "Something Has gone wrong" is not the first question in the vanilla documentation either. It is Backend. and troubleshooting is at the end.

    http://docs.vanillaforums.com/developer/

    take a look at FAQs - you will see they all slavishly adhere to a common sense logical order of the Table of Contents and most have question numbering in the TOC as well.

    http://www.faqs.org/faqs/joel-furr/faq/

    https://vanillaforums.org/discussion/comment/218971/#Comment_218971

    please edit title to WHU606's inconsistent adherence to a Table of Contents in the FAQ

    you lack visual logic. And this has nothing to do about coding. it has to do with following a standard and a visual flow. and the ability to understand the basics of Table of Contents in English despite your education, whatever it may be.


    your TOC looks like this

    Pragmatism is all I have to offer. Avoiding the sidelines and providing centerline pro-tips.

  • whu606whu606 I'm not a SuperHero; I just like wearing tights... MVP
    edited December 2016

    But I am through with this and you.

    Well, that's a relief.

    I've have tried to educate you to improve things and conform to the world's view of a TOC. you can iyoo - in your own opinion do what you need to do and renege on your offer to follow my suggestions out of a decision to break with conformity.

    I already have a pretty good education, which includes a degree in English, so I'm fairly confident in my opinions and understanding in regards to this issue.

    In publishing terms, a ToC is created after the material has been ordered in the editing process.

    I can't think of a sane example where an editor would insist on or agree to publishing multi-author material strictly on the order that it was received.

    The point of FAQs is to allow new users to find answers to the questions that most frequently occur. (Kind of a giveaway in the name don't ya think?) Given that, I think that putting the most commonly occurring questions near the top of the list is a reasonable move.

    I'm certain you know an awful lot more than me in terms of coding, so perhaps you should stick to your strengths?

Sign In or Register to comment.