Skip to content

UserGuideTemplate

jpeterka edited this page Apr 26, 2013 · 12 revisions

Basic rules writing RedDeer User Guide

When you received task to create wiki User Guide section , it refers to pages under User Guide wiki page (https://github.com/jboss-reddeer/reddeer/wiki/User-Guide)

These are basic rules and good principles that user wiki section page should fulfill:

  • it should be example driven (examples and small tutorials), for API specifics there is javadoc
  • from simple to complex - start with simple examples
  • use syntax formatting and images when referring to somthing that can be shown visually
  • start with simple introduction (API and usage) and follow with examples
  • warn users about possible issues there and unsupported scenarios
  • if page grows please split it into multiple documents so it user can find particular information quickly from main User Guide Page
  • if referring to real example doc should link to existing code in org.jboss.reddeer.examples (formely wiki - this will be updated)
  • when it's finish please update main UserGuide wiki page
  • Userguide page is just content page, don't add content there directly
  • Make it interactive if possible, more pictures, screenshots and videos are welcome

Possible template example (not suiteable for all sections)

Some Example of API usage how it can be structured

API / Abstract

  • Interface / Abstract

Implementation(s)

  • Impl1
  • Impl2
  • Impl3

Usage

Implementation

Lookup for ...."

// code

Operation1

// operation code

Short notation

// code

Specific wiki page (just the beginning)

See example below, go from simple to more complex, add whatever details that are important, focus mainly on examples with comments

API / Abstract

  • Button / AbstractButton

Implementation(s)

  • PushButton
  • CheckButton
  • RadioButton

Usage

Implementation

image

Lookup for a button with text "Apply"

Button b = new PushButton("Apply");

Click a button

b.click(); 

Short notation

new PushButton("Apply").click();

... more complex examples, other implementations

Clone this wiki locally