WoW-Pro Addon Style Guidelines

WoW-Pro Addon Style Guidelines




The 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


  1. Auto-Completion
  2. Note Tags
  3. Note Steps
  4. Quest Objective Tags
  5. PRE Tags
  6. LEAD Tags
  7. RANK Tags
  8. QIDs for Non-Quest Steps
  9. Coordinates
  10. Sticky Steps
  11. 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.

[Back to top]




Note Tags


Note tags, aka |N|, contain a brief explanation of what to do for that step.

Frequency of Use:

Length:

[Back to top]




Note Steps


Note steps should be avoided whenever possible. If you are about to use one, first consider one of the following step types:

Sometimes you absolutely have to use a N step, and that's okay - but avoid it as much as you can.

[Back to top]




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:

Times to use a |QO| tag:

Time to use a single C step with multiple coordinates:

[Back to top]




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.

[Back to top]




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.

[Back to top]




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|

|RANK|2|

|RANK|3|

[Back to top]




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:

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.

[Back to top]




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

|CC| and |CS| tags

[Back to top]




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.

[Back to top]