blob: ed0d5aa13e3f633a194f240da94f480eeac8906f [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Documentation Style Guide</title>
<link href="//,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
<a href="" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="" alt="Fork me on GitHub">
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce-2021.html">Announcements</a></li>
<li><a href="">License</a></li>
<li><a href="">Thanks!</a></li>
<li><a href="">Sponsorship</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="">Version Notes</a></li>
<li><a href="">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="">FAQs</a></li>
<li><a href="">Plugin registry</a></li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
<li class="apache"><a href=""><img src="/img/apache.png"></a></li>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="" title="Edit this page on GitHub">Edit on GitHub</a>
<a href="index.html" title="back to Contributors Guide"><< back to Contributors Guide</a>
<h1 class="no_toc" id="documentation-style-guide">Documentation Style Guide</h1>
<ul id="markdown-toc">
<li><a href="#do-it-now-do-it-once-do-it-well" id="markdown-toc-do-it-now-do-it-once-do-it-well">Do it now. Do it once. Do it well.</a></li>
<li><a href="#capitalization-of-common-terms" id="markdown-toc-capitalization-of-common-terms">Capitalization of common terms</a></li>
<li><a href="#general-punctuation-and-grammar" id="markdown-toc-general-punctuation-and-grammar">General Punctuation and Grammar</a></li>
<li><a href="#quick-tips" id="markdown-toc-quick-tips">Quick Tips</a></li>
<li><a href="#dont-be-smurfy" id="markdown-toc-dont-be-smurfy">Don’t be smurfy!</a></li>
<li><a href="#page-save-comment" id="markdown-toc-page-save-comment">Page Save Comment</a></li>
<li><a href="#parent-pages" id="markdown-toc-parent-pages">Parent Pages</a></li>
<li><a href="#labels" id="markdown-toc-labels">Labels</a></li>
<li><a href="#avoid-skipping-headers" id="markdown-toc-avoid-skipping-headers">Avoid skipping headers</a></li>
<li><a href="#more-on-text-effects" id="markdown-toc-more-on-text-effects">More on Text Effects</a></li>
<li><a href="#text-breaks" id="markdown-toc-text-breaks">Text Breaks</a></li>
<li><a href="#lists" id="markdown-toc-lists">Lists</a></li>
<li><a href="#images" id="markdown-toc-images">Images</a></li>
<li><a href="#tables" id="markdown-toc-tables">Tables</a></li>
<li><a href="#advanced-formatting" id="markdown-toc-advanced-formatting">Advanced Formatting</a></li>
<li><a href="#change-happens" id="markdown-toc-change-happens">Change Happens</a></li>
<p>It’s well-known that a consistent user interface is easier to use. Consistency helps users focus on the task rather
than the user interface. Likewise, a consistent documentation style helps users focus on the information, rather
than the formatting.</p>
<p>A related goal is to design the documentation so that it is easy to maintain, so that it tends to remain internally
consistent with the framework itself.</p>
<h2 id="do-it-now-do-it-once-do-it-well">Do it now. Do it once. Do it well.</h2>
<p>Overall, there are three goals for the documentation system.</p>
<li>Say it all</li>
<li>Say it once</li>
<li>Say it well</li>
<p>First, we want the documentation to be both complete and concise. This is job one! The documentation should also be a quick
but practical introduction to the framework, so newcomers can get started as easily as possible. To keep people coming back,
the documentation should also be a repository of the tips and tricks we use in our own applications, so that people can find
it here instead of asking over and over again on the list.</p>
<p>Second, the documentation should be easy to maintain. Ideally, we should cover the detail of each topic once, and draw
as much detail from the source code and examples as possible (using the <em>snippet macro</em>).</p>
<p>Third, the documentation should be text-book quality; if not in the first draft, then in the next. Don’t hesitate
to hack in a new page. Better that we have the page than we don’t. (See Job One!) But, as time allows, we should try
to make each page the best that it can be. A great many people access the documentation, and it’s worth the effort
to make the “documentation experience” productive and enjoyable.</p>
<h2 id="capitalization-of-common-terms">Capitalization of common terms</h2>
<h2 id="general-punctuation-and-grammar">General Punctuation and Grammar</h2>
<p>Good online resources for punctuation, grammar, and text style include</p>
<li><a href="">Wikipedia Manual of Style</a></li>
<p>In print, two excellent (and inexpensive!) resources are</p>
<li><a href="">The Elements of Style</a></li>
<li><a href="">Associated Press Stylebook</a></li>
<p>Also excellent, but more expensive:</p>
<li><a href="">Chicago Manual of Style</a></li>
<h2 id="quick-tips">Quick Tips</h2>
<li>Use as few words as possible. Instead of “but there are some quirks about it” try “but there are quirks”.</li>
<li>If a list of items includes both a term and an explanation, consider using a table instead of bullets.</li>
<li>Avoid using “This” by itself. Instead of “This lets us” try “This strategy lets us”.
<li>Ask yourself: “This what?”</li>
<li>References to other wiki pages can be unqualified. For example: “See .”</li>
<h2 id="dont-be-smurfy">Don’t be smurfy!</h2>
<p>A lot of API members use the term “action”. We have</p>
<li>action extensions on pages,</li>
<li>action attributes in forms,</li>
<li>action elements in configuration files, and</li>
<li>Action Java classes, some of which may implement the</li>
<li>Action interface.</li>
<p>Here are some terms that can be used to help clarify which action is which.</p>
<li>Use “the framework” or “Struts 2” to refer to the codebase as a whole, including any frameworks we use internally, like OGNL.</li>
<li>Use “Action class” or “action handler” to refer to the Java class incorporated by the action element.</li>
<li>Use “action mapping” to refer to the object created by the action element.</li>
<h2 id="page-save-comment">Page Save Comment</h2>
<p>Try to include a brief description of a change when saving a page. The comments are included in the page’s history.
The comments are also included on the daily change report. In a group environment, it’s important to help each other follow along.</p>
<h2 id="parent-pages">Parent Pages</h2>
<p>Use the Parent Page feature to create a hierarchy of pages. The parent pages are reflected in the “bread crumb” menu.
If properly used, parent pages can help browsers “visualize” the documentation as an outline.</p>
<p>The root of the documentation is the “Home” page, which is also the “Welcome” page. The documentation is ordered into
three main areas: Tutorials, FAQs, and Guides. Each area has a contents page, whose parent is Home. Other pages within
each section can also serve as parents, to help organize the documentation into a coherent outline.</p>
<h2 id="labels">Labels</h2>
<p>Pages can be cross-indexed with the Label feature. Labels are not be used much yet, except for internal authoring.</p>
<th>A page that mentions a problem in the distribution that we intend to fix. Review these pages before tagging a distribution to see if the issue has been resolved.</th>
<td>A page that is incomplete. Try to complete these pages before tagging a distribution</td>
<h2 id="avoid-skipping-headers">Avoid skipping headers</h2>
<p>The headers form an outline for the page. When writing term papers, it is not a good practice to skip outline levels.
When writing hypertext, it is not a good practice to skip heading levels either. Try not to skip from a <code class="highlighter-rouge">h2</code> to a <code class="highlighter-rouge">h4</code>.</p>
<p>If you find yourself writing too many h2 headings in a single page, consider breaking the page into child pages.</p>
<h2 id="more-on-text-effects">More on Text Effects</h2>
<p>Text effects like <strong>strong</strong>, <em>emphasis</em> , and inserted can be used in the usual way to denote important parts of a sentence.</p>
<p><code class="highlighter-rouge">Monospaced</code> should be used to files, tags, and methods, like <code class="highlighter-rouge">struts.xml</code>, <code class="highlighter-rouge">&lt;xmltag /&gt;</code>, and <code class="highlighter-rouge">execute</code>.
Class and Interface names may be left in normal face, like Action and Interceptor.</p>
<p>A panel should be preferred to a block quote. The color fonts should be avoided or used only with great care.
Some people have difficulty seeing some colors, and the colors may not be apparent if the page is printed.</p>
<h2 id="text-breaks">Text Breaks</h2>
<p>Text breaks should not be used to format blocks on the screen. If there is an issue with the way paragraphs or headings
are being rendered, we should customize the stylesheet.</p>
<h2 id="lists">Lists</h2>
<p>Unordered lists should be created only with the <code class="highlighter-rouge">-</code> notation.</p>
<p>Ordered list should be used when numbering the items is important. Otherwise, prefer unordered lists.</p>
<li>This is an unordered list in star notation;</li>
<li>Items can have sub-items
<li>That can have sub-items
<li>That can have sub-items …
<li>What is the limit?</li>
<li>Mixing ordered and unordered lists is possible:
<h2 id="images">Images</h2>
<p>Avoid using external images for bullets or icons. Prefer the equivalents provided with Confluence.</p>
<p>Images can be included by URL or annexing the binary to the page. Prefer annexing when possible, since URLs are subject to change.</p>
<p>Always observe copyright issues. Do not annex images unless it an original or public domain work, or the author has donated the image to the foundation.</p>
<p><img src="" alt="" /></p>
<h2 id="tables">Tables</h2>
<p>Prefer lists for single-value entries. Prefer tables for lists with multiple columns.</p>
<p>Tables are very useful when lists just don’t do it. Meaning: don’t write a table when a list suffices. Tables are more
organized, because you can align the text in columns. Since the markup text for tables in Confluence is not easy to read,
complex and big tables can be hard to maintain.</p>
<th>Location (relative to webapp)</th>
<td><code class="highlighter-rouge">web.xml</code></td>
<td>Web deployment descriptor to include all necessary WebWork components</td>
<td><code class="highlighter-rouge">struts.xml</code></td>
<td>Main configuration, contains result/view types, action mappings, interceptors, and so forth</td>
<h2 id="advanced-formatting">Advanced Formatting</h2>
<p>Try to specify the language for ``` … ``` blocks.</p>
<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/** Hello World class. */</span>
<span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloWorld</span> <span class="o">{</span>
<span class="cm">/** Main method. */</span>
<span class="kd">public</span> <span class="kd">static</span> <span class="kt">void</span> <span class="nf">main</span><span class="o">(</span><span class="n">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span>
<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Hello, World!"</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span>
<p>Avoid tabs in code blocks, use two spaces instead. Long lines should be formatted to fit in a 800x600 resolution screen,
without resorting to horizontal scrolling.</p>
<p>A typical example of “non-lang” block would be the command line statements to compile and run the code above.</p>
<p>The terminal notation <code class="highlighter-rouge">$</code> should be used to represent a system prompt.</p>
<p><strong>Compiling and Running Hello World</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ javac
$ java HelloWorld
Hello, World!
<h2 id="change-happens">Change Happens</h2>
<p>Anyone who has worked with databases knows the value of normalizing the schema. Ideally, we want to store each fact
exactly once, and then use query system to retrieve that fact wherever it is needed. If we store a fact once, we only
need to update it once, and we avoid inconsistencies in our data set.</p>
<p>To the extent possible, we want to “normalize” our technical documentation. Like a database, all technical documentation
is subject to change. When change happens, we want the documentation to be as easy to update as possible. One way to do
that is to try and minimize redundancy (without sacrificing ease of use).</p>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="">The Apache Software Foundation </a>.
All Rights Reserved.
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
<div class="col-md-12">Logo and website design donated by <a href="">SoftwareMill</a>.</div>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "twitter-wjs");</script>
<script src="" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); = id;
js.src = "//";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>