The User's Guide is there to provide two basic kinds of information.

It is a guide for how and why to use each feature or mechanism of OpenOCD. It is also the reference manual for all commands and options involved in using them, including interface, flash, target, and other drivers. At this time, it is the only documentation for end users; everything else is addressing OpenOCD developers.

There are two key audiences for the User's Guide, both developer based. The primary audience is developers using OpenOCD as a tool in their work, or who may be starting to use it that way. A secondary audience includes developers who are supporting those users by packaging or customizing it for their hardware, installing it as part of some software distribution, or by evolving OpenOCD itself. There is some crossover between those audiences. We encourage contributions from users as the fundamental way to evolve and improve OpenOCD. In particular, creating a board or target specific configuration file is something that many users will end up doing at some point, and we like to see such files become part of the mainline release.

General documentation rules to remember include:

Be concise and clear. It's work to remove those extra words and sentences, but such "noise" doesn't help readers.
Make it easy to skim and browse. "Tell what you're going to say, then say it". Help readers decide whether to dig in now, or leave it for later.
Make sure the chapters flow well. Presentations should not jump around, and should move easily from overview down to details.
Avoid using the passive voice.
Address the reader to clarify roles ("your config file", "the board you are debugging", etc.); "the user" (etc) is artificial.
Use good English grammar and spelling. Remember also that English will not be the first language for many readers. Avoid complex or idiomatic usage that could create needless barriers.
Use examples to highlight fundamental ideas and common idioms.
Don't overuse list constructs. This is not a slide presentation; prefer paragraphs.

When presenting features and mechanisms of OpenOCD:

Explain key concepts before presenting commands using them.
Tie examples to common developer tasks.
When giving instructions, you can @enumerate each step both to clearly delineate the steps, and to highlight that this is not explanatory text.
When you provide "how to use it" advice or tutorials, keep it in separate sections from the reference material.
Good indexing is something of a black art. Use @cindex for important concepts, but don't overuse it. In particular, rely on the @deffn indexing, and use @cindex primarily with significant blocks of text such as @subsection. The @dfn of a key term may merit indexing.
Use @xref (and @anchor) with care. Hardcopy versions, from the PDF, must make sense without clickable links (which don't work all that well with Texinfo in any case). If you find you're using many links, read that as a symptom that the presentation may be disjointed and confusing.
Avoid font tricks like @b, but use @option, @file, @dfn, @emph and related mechanisms where appropriate.

For technical reference material:

It's OK to start sections with explanations and end them with detailed lists of the relevant commands.
Use the @deffn style declarations to define all commands and drivers. These will automatically appear in the relevant index, and those declarations help promote consistent presentation and style.
- It's a "Command" if it can be used interactively.
- Else it's a "Config Command" if it must be used before the configuration stage completes.
- For a "Driver", list its name.
- Use EBNF style regular expressions to define parameters: brackets around zero-or-one choices, parentheses around exactly-one choices.
- Use @option, @file, @var and other mechanisms where appropriate.
- Say what output it displays, and what value it returns to callers.
- Explain clearly what the command does. Sometimes you will find that it can't be explained clearly. That usually means the command is poorly designed; replace it with something better, if you can.
- Be complete: document all commands, except as part of a strategy to phase something in or out.
- Be correct: review the documentation against the code, and vice versa.
Alphabetize the @defn declarations for all commands in each section.
Keep the per-command documentation focused on exactly what that command does, not motivation, advice, suggestions, or big examples. When commands deserve such expanded text, it belongs elsewhere. Solutions might be using a @section explaining a cluster of related commands, or acting as a mini-tutorial.
Details for any given driver should be grouped together.

The User's Guide is the first place most users will start reading, after they begin using OpenOCD. Make that investment of their time be as productive as possible. Needing to look at OpenOCD source code, to figure out how to use it is a bad sign, though it's OK to need to look at the User's guide to figure out what a config script is doing.