by JiyambiThe style of a guide includes many things. In broad terms, when you have two possibilities that both work, and you have to pick one, that’s a style decision. This guide will cover the most common of these decisions, and give recommended ways to handle those situations in your guides.
Why do we want to handle these situations in the same way? The main reason is that we want the user to have a uniform experience with our guides. That means that, even though the guides are by different people, we want it to feel like one big guide. When things change a lot between guides, it can be confusing to the user, and even if they don’t become confused, it seems jarring and unprofessional.
Because of this, please keep these style guidelines in mind when coding or recording your guides!
If you think of something that should be listed here, please leave a comment!
NOTE: General coding questions will not be discussed here, see the Syntax Page for that.
Table of Contents
- Auto-Completion
- Note Tags
- Note Steps
- Quest Objective Tags
- PRE Tags
- LEAD Tags
- RANK Tags
- QIDs for Non-Quest Steps
- Coordinates
- Sticky Steps
- Comments
Auto-Completion
Whenever possible, make your steps auto-complete. If you have a note to give the user, first think and see if it would make sense to add it as a note or use optional tags to only have the step show if needed. We want the user to not have to think about the guide at all, and auto-completing is one of the best ways to do that.
Note Tags
Note tags, aka |N|, contain a brief explanation of what to do for that step.
Frequency of Use:
-
- Note tags should be used on almost every step. If you are using the recorder, it will automatically create note tags with NPC names when you accept or turn in quests and for most other tasks. These are usually fine, though sometimes they could do with a bit of extra explanation.
It will NOT automatically add notes for quest complete steps. Make sure you add in a sentence explaining what to do.
Length:
- Note tags should be between one and three sentences long, most times only one sentence.
Note Steps
Note steps should be avoided whenever possible. If you are about to use one, first consider one of the following step types:
- C – Complete: Are you completing one of the objectives for a quest? Use a C step and a |QO| tag!
- K – Kill: Are you killing a mob until you get a certain item? Use this step type and a |L| tag!
- l – Loot: Are you looting items from the world environment? Use this step type and a |L| tag!
- U – Use: Are you asking the user to use an item? This step won’t auto-complete on it’s own, but it’s a better visual cue than just a normal note step.
- B – Buy: Asking the user to buy something? Use a |L| tag with this step and make it auto-complete!
- r – Repair/Restock: Telling them to repair and restock? We have an icon for that! It won’t auto-complete, but it is a better visual cue.
- L – Level: Letting them know they should be a certain level? Use a L step and a |LVL| tag for auto-completion!
Sometimes you absolutely have to use a N step, and that’s okay – but avoid it as much as you can.
Quest Objective Tags
Quest objective tags are a very powerful tool, but it can be hard to know when to use them and when to simply provide several coordinates in the |M| tag instead of breaking it into several steps.
Some quick notes:
- Use a C type step with |QO| unless you have a very good reason to use a different step type.
- Instead of using the quest text as the step text, use the QO text.
- Remember to also use a |NC| tag if you aren’t doing something involving combat.
Times to use a |QO| tag:
- Quest parts are completed at different times
- Quest parts are completed in a very sequential order
- Quest parts have distinct, stationary locations
Time to use a single C step with multiple coordinates:
- All quest parts are complete in the same general area at the same time
PRE Tags
PRE tags should be used for on A type steps only, unless you are using them with an |O| tag to determine when the |O| step displays.
Check every A step in your guide to see if you should give it a |PRE| tag. We NEED any quest with a prerequisite to have one of these tags, because they are use in our quest skipping logic.
LEAD Tags
LEAD tags are for lead-in quests. The QID in this tag is one such that, if that QID is completed, the current step will not be available and should also be checked as completed.
These tags are important for users who might be jumping into our guide mid-way through, so make sure to check them when you can! I know these are harder to check than PRE tags, but do your best.
RANK Tags
Rank tags are one of our most important features. These tags allow us to place importance on quests and help users figure out which quests can be skipped (or rather, help our guide figure out which quests to skip for the user)
|RANK|1|
- You don’t need to use it, it’s implied if no rank is listed. Never skipped no matter what setting. Use for quest chains that lead to the “final” quest in the zone. I’m not sure how the high level zones go, but for the mid level ones there is usually one quest that yields very high quality rewards and “finishes” the story for that zone. All quests leading up to and including this kind of a quest should be rank 1.
|RANK|2|
- These steps are only skipped by people on the lowest completion setting. Use this for quest chains that don’t lead to the “final” quest – though NOT if there are a ton of quest chains like this. I would say as a general guideline, between 1/4 and 1/3 quests should have this tag.
|RANK|3|
- Really our of the way or annoying quests with little return. I haven’t been using it too often. Something the typical user would NOT want to do, something only completionists would want to do.
QIDs for Non-Quest Steps
EVERY STEP must have a QID. There are many reasons for this. A lot of the code in the addon references things by QID. A very important reason is to allow someone to jump in partway through – the only thing we can know about a new user is what quests they have completed, so we have to be able to catch them up to the right point in the guide based on this alone.
To choose a QID for a step that is not related to a quest:
- Think about what QID would make that step not important anymore. Are you telling them to get a flight path? If they have a quest from that hub already, they probably already have the FP, so you can use a QID from one of the early steps.
- If you can’t think of a logically connected quest, just use the QID for the next step they turn in after the step in question.
Please do not use “placeholder” QIDs. You should be able to find some QID that gets completed within the guide to use as the “placeholder” instead, and it’s important that we do this so people can jump in at any point.
Coordinates
Add coordinates for everything you possibly can, even if it seems obvious. Luckily if you are using the recorder, most of these will be automatically recorded. Be careful though – if quest is picked up from a non-NPC, you may not get coordinates for it.
Multiple Coordinates
- Multiple coordinates can be added by separating coordinates pairs with a semicolon (;). This should be done when…
-
- Showing the user a route (make sure you place the waypoints in places they will certainly run close to)
- Showing the patrol path for a mob
- Showing several possible places something might spawn
|CC| and |CS| tags
- These tags can be used with R type steps to make a step auto-complete when the user reaches the coordinate (|CC|) or series of coordinates (|CS|), rather then when they reach the subzone name. Use these sparingly, and think carefully whether a simple multiple coordinate step might work better.
Sticky Steps
Sticky steps are one of our most innovative features, and should be used whenever it makes sense to do so. Any time you have a set of two or more steps that the user is completing at once, use a sticky step. For how to use these steps, see the Syntax Page.
