How to Write a How-To

A How-To is a short wiki article that provides detailed, step-by-step instructions about how to accomplish a specific task. This page describes how to write a GlassFish How-To. Your contributions are governed by the Terms of Use.

Questions or comments about any of this? Don't hesitate to contact the doc team.

Before You Begin

Writing the How-To

See Also

Basic How-To Template

Before You Begin

A few general guidelines before you begin:

• Know your audience and the specific objective of your How-To.

• Search the GlassFish wiki to make sure a How-To for your topic doesn't already exist.

• Choose your title carefully – the best titles are short and include key words likely to be used in a search (for example, "How to Configure a Basic Cluster").

• Always include examples if possible and the complete steps to accomplish the task.

• Always provide attribution for outside sources and content.

• Test your work to make sure the procedure can be performed as described.

• Clean up your work and revise, revise, revise as necessary.

• Jump in and give it a try! Your first attempt doesn't need to be perfect. This is a wiki, after all, so if something's not quite right it can be easily fixed.

Writing the How-To

1. Check the Community Docs Wish List on the Community Docs page to see topics that need to be documented, or identify a topic of your own.

1. Send an e-mail to the documentation mailing list, describing what you intend to contribute.

1. Log in to the GlassFish wiki (see the login FAQ if you don't yet have a login) and record the document you're working on in the Community Docs in Progress table on the Community Docs page.

1. Create a new wiki page for your How-To, using the Howto_ prefix in the page name (important!). One way to create the new page:
   • Enter the new page name in your browser's Location Bar. For example, in the URL http://wiki.glassfish.java.net/Wiki.jsp?page=CommunityDocs, change CommunityDocs to Howto_DoSomething, where Howto_DoSomething is the actual name of your page. For example, Howto_ConfigureABasicCluster.
   • Press Return/Enter, and then opt to create the new page when prompted.

1. Copy and paste the basic How-To template into your new wiki page.

1. Follow the instructions in the template and create your article, revising, previewing, and saving as necessary.

1. When your How-To page is finished:
   • Record your contribution on the Community Docs page in the Community Docs Contributions table.
   • Add a link to your How-To on the GlassFish How-To's page.
   • Send an e-mail to the doc team, indicating the doc is done.
   • Start another How-To!

See Also

• GlassFish style sheet
• Wiki Text Formatting Rules

Basic How-To Template

Use this basic WikiText template for your How-To. The template was used for this How-To page.

!!!How to Do Something

Summarize your article so readers can decide quickly whether 
to read it.


!!Before You Begin
List anything readers must do to prepare for the task. Also
provide any background knowledge readers must possess to make
sense of your example or carry out your instructions.


!!Doing Something
Provide steps that tell readers how to accomplish the task.
Include examples whenever possible. Good examples with explanatory
text are critical to writing effective HowTo's. Break one large
procedure into several smaller ones to avoid having more than
about 7-9 steps per procedure. 


!!See Also
Provide links to related information that would be helpful to your
readers but which doesn't fit in your HowTo.