A Styles FAQ

komrade

Hi All,

I've done a rough draft of a Styles FAQ page for the wiki.

Any input would be very useful - please go ahead and edit, or let me know how you think it can be improved - or if it's even needed.

Inspired by (and plagiarising) AdamSmith's simple guide to making changes which is regularly referenced in the forums, I've also adapted it a bit and made a page on making simple CSL edits.

Again, any and all input into this would be fantastic!

Hope this is useful. Let me know if you think I've missed anything big, or if any of this will be useless in a few weeks(?) when CSL 1.0 is launched onto the world!

adamsmith

the FAQs look great!
The Simple CSL edits is a very good start. I think we should beef it up with some pictures and a little more info about the structure of styles, so people can navigate successfully. I'll try to chip in over the weekend.

dstillman

komrade: Thanks for starting this.

For questions that are frequently asked on the forums, it's probably a better idea to put that actual content in KB articles on the wiki and link to those from the FAQ. We've moved away from FAQ pages for other documentation because the (named anchor) links are dependent on the exact wording of the question, and having a short descriptive URL pointing to a dedicated page makes things easier for everyone.

Rintze

Let me know if you think I've missed anything big, or if any of this will be useless in a few weeks(?) when CSL 1.0 is launched onto the world!

I haven't look at everything in detail, but it looks like a welcome addition to the documentation. Also, most of what you've written will remain relevant for CSL 1.0 (only some links will change).

komrade

@ Dan

OK - accepted that this is the current standard, but it's also nice to be able to read all 9 points in one go without having to click 18 times.

I think the current FAQ is also not ideal in this regard. The links aren't all that easy to read, and it would be nice to see it all in one page.

I'll transfer the info to individual kb items over the weekend, but I'd like to somehow have a way of seeing it all. Any ideas? I know other sites have the list of questions at the top, linking to each question further down the same page. Or they have java-style + boxes expanding the answers.

dstillman

it's also nice to be able to read all 9 points in one go without having to click 18 times.

Well, I'm not suggesting that each answer be a KB article—just the ones that have semi-substantial answers and that are asked frequently here, such as the font one. FAQ or not, people are going to ask the questions here, and we're going to be able to need to link to them, and using the named anchors that DokuWiki generates is not a reliable method.

One solution would be a custom KB front-end that could pull content from individual KB articles into grouped lists, but that's probably not going to happen anytime soon.

I think the current FAQ is also not ideal in this regard. The links aren't all that easy to read, and it would be nice to see it all in one page.

What are you referring to? The main FAQ page? I agree that that page isn't great, but neither is duplicating content and maintaining it in two separate places, and the value of permanently linkable KB articles has been proven pretty clearly in the forums. The questions remaining on that page are the most frequently asked questions, but really we probably shouldn't bother with that page at all and should just emphasize using search instead, adding additional tags to the KB articles as necessary to ensure that they show up for common searches.

komrade

Yeah - that's the page I meant.
Your emphasis on search is sensible for most people, though I do find it useful (on other sites) to read through the FAQ. It's often a de-facto tips and tricks page (though of course you have one of those already.

How are tags added into the KB articles?

And is there a clever way of sorting the KB section, say by the number of hits, so that frequently asked questions bubble up to the top? Just a thought.

Tjowens

You add tags to pages by adding this
{{tag>tagname secondtag}}
Note, we can also add multiple tags to a page, for example we could create a tag for cslfaq and then generate a page of links from cslfaq and still have all of the individual items in the kb as well. This might actually be a better way to generate the FAQ, just through the faq tag onto kb items that are particularly frequent.

If you put this chunk of code with the tag you want to use you will generate a list of items with that tag on the page.
{{topic>tagname&nouser&nodate}}

komrade

OK I've transferred the answers into kb articles, tagged them with csl_faq and generated a list at the original Styles FAQ page (with a brief preamble).

I guess there's no way to change the order that the tagged items are returned (alphabetic) or the name of the item (it's first heading).

It makes sense to do it like this for the main FAQ page too, but without being able to change the label, it will be confusing
(e.g. the first item would come out as
"Zotero Data Fundamentals"
instead of
"How do I back up my data?"

komrade

I'd also appreciate any input into this page on standards, which is linked from the new Styles FAQ.

mark

The standards page is neat. And I like the KB pages implementation of your FAQ.

komrade

Now wouldn't it be nice if journals stuck to those standards, instead of making their own arbitrary changes!

I've enjoyed these two articles on the craziness of the current situation, from the Times Higher Education Supplement, and a blog.

Unfortunately, Gill's solution to having 3000 citation methods was not to force publishers to stick to the existing standards, but to invent another one!

komrade

None of the pages that I added to the wiki on styles (e.g.) have been indexed by the Zotero search (or Google).
Is there something special that needs to be on the page to get searched and/or indexed?