HowTo and FAQ Style Guide

From ADempiere
Revision as of 13:50, 3 June 2010 by MJMcKay (Talk) (The Title & Category)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.

This style guide is intended to provide wiki contributors with a template and style suggestions to use when writing HowTo articles and Frequently Asked Questions (FAQs).

Writing FAQ Entries

Frequently Asked Questions (FAQs) are intended to reduce the workload and traffic in the forums by putting the replies to common questions in a single location where they can be easily found. The format for a FAQ should follow a question / answer pattern. The questions should be similar to what is asked in the forums and stated explicitly as a question. The answer needs to be short with links to further reading if required.

The wording in the question should reflect the level of knowledge of the intended user and avoid terminology they may not understand at the time they ask the question. The question should also reflect a specific task the user is trying to perform. For example:

  • Bad: How do I use the application dictionary?
  • Better: How do I add a column to a table?
  • Better yet: How do I add a new field to a window form?

When writing the FAQ, keep the intended user in mind. Basic questions from first time users can be treated differently than complex questions from developers. In the organization of the FAQs, place the question/answer in the appropriate hierarchy.

There is a template for FAQs here Template:FAQ

To use it, enter your question and answer pair as follows:

{{FAQ|question=How do I use the FAQ Template?|answer=Just like this. Note that the variable names are case sensitive. The template uses heading level five for the question so it will appear in a table of contents.}}

The result will appear in the page as follows:


Q: How do I use the FAQ Template?
Just like this. Note that the variable names are case sensitive. The template uses heading level five for the question so it will appear in a table of contents.

Howto Write a HowTo Guide

HowTo articles explain in detail the process to acomplishing a task. To be effective, the HowTo should be written with a target audience in mind and should provide the reader with something to learn along the way. Keep it simple and break the task into smaller chunks and articles if needed.

Before you Begin

Gather all the information you will need before you begin to write the article:

  • Know your subject area and have a good explanation for the task at hand. Research the parts you may not know well.
  • Understand who you are writing the article for. The level of detail and the complexity of the steps will vary significantly with the target audience, as will the assumptions about what you think the reader already knows. Be consistent throughout the article and ensure it is properly focused.
  • Have everything ready for a demonstration. Perform the task and capture screen shots at key points. Make note of the starting conditions and any assumptions on the state of the application, database and hardware.
  • Write the article in an application that has a spell checker.
  • Have someone proofread the article or ask for help in the ADempiere Documentation forum.

The Title & Category

Choosing the correct title is important in a wiki article since you want people to find the information when they are looking for a solution to their problem. Avoid using the words How To or HowTo as the first words in the title. Instead try to start the title with the main subject area and end with action the article is trying to perform - but make it readable. Also keep in mind that the article will appear in lists alphabetized by title.


Note.gif Note:

The Media Wiki search does not index every word. Small words like “How” and “To” are not indexed and won’t appear in the search. If you search the wiki for “How To” to get a list of how to pages, the search will be blank. It is easier to use categories to get a list of How To pages.

The title should also include a key word describing the main subject of the article. For example:

  • Writing a HowTo guide
  • Processes, How to Write one for ADempiere
  • Processing Documents

You should also include all relevant categories for the HowTo article to help readers find it. One obvious category is HowTo. Ensure you add it to the page like this:

[[category:HowTo]]

Introduction

At the very beginning of the article, tell people what you are going to tell them. This will save people time as they look for a solution to their problems. If you just launch into the steps without the description, people will likely not read the details to figure it out.

Tell the Reader what they will need to complete the HowTo

Before you get into the details, tell the reader what they will need to complete the steps in the article. It would be very annoying to get to step 11 in a long process to learn the article only applies to Ubuntu installations. This is like a recipe list of ingredients.

Break down the steps

Remember your target audience and their expected level of knowledge. Break down the steps to the level they will understand and no further, but do break it down. People are reading the article as a checklist so don’t gloss over important steps in an effort to be simple.

Educate as you go

In addition to providing a checklist, your article should help people learn. Include information about the processes or the application that will enlighten the reader and help them understand why the process is performed this way.


Note.gif Note:

A great way to do that is to use the Note template. It can be added to your articles like this:

{{Note| A great way to do that is to use the Note template.  It can be added to your articles like this}}

You can also add learning points in-line with the article.

Prepare for problems

Prepare for problems the reader may encounter if they do things incorrectly. Use screen shots to show what to expect and suggest solutions if they are having problems.

Make a Conclusion

At the end of the article, conclude what you have told the reader. Make a summary list of the key points and what the reader should have learned.

Categorize and Link

Don’t leave the article hanging. Make sure people can find it when they are looking for help. Add the proper category tags and link the article to other similar pages. Add links to your article in indexes or other pages.

When all is done, ask for kudos in the ADempiere documentation forum.

Thanks for contributing!