Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
wiki:how-to_formating_suggestions [2009/05/11 23:21] – jaywiki:how-to_formating_suggestions [2024/06/27 00:08] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== How-To Formatting Suggestions ======
  
 +Here, we'd like to make some suggestions around formatting a How-To. Please review the syntax page to view the specifics about wiki markup.
 +
 +  - Try to use the "Ordered List Item" button in the editor. This will create a nice numbered list. The goal is to create a page that a user less experienced than you can use to implement your feature. Simple numbered steps make this much easier. Some How-To articles are more for background and don't really lend themselves to ordered list - that's OK too, just make sure you use the appropriate approach for your How-To.
 +  - Some say a picture is worth a thousand words. And, that may be the case with your solution. To help keep bandwidth usage down and available disk space up, please use pictures judiciously and make sure they're as small as you can make them and still be useful.
 +  - When in doubt, always over-explain what to do or what a step will accomplish. This will not only make your How-To more successful, but will hopefully educate the user.
 +  - Having said the last point, limit alternative ways of performing a particular action. If there are 3 different ways of accomplishing a task, pick one and be consistent. Choice is good, but inexperienced users who are looking for a specific solution don't need to know that there are multiple ways of accomplishing a task. Remember, they just want a solution to a problem as quickly as possible.
 +  - Various solutions are inherently gonna be harder than others. So, you should give the user an up-front estimation of how difficult something will be following the standards here: [[How-to level of difficulty]] 
 +  - Please try to use **bold** and ''code text'' when indicating a word, menu, option, etc. in the Indigo Client UI. It's easier for people to understand that you need to click the **''New...''** button (as opposed to just the New... button). Use the B and TT buttons above the editor window to insert bold and code text wiki markup codes.
 +
 +If you follow these suggestions as closely as possible, users will be able to use and understand your How-To quickly and the community as a whole will become even more knowledgeable!