| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <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="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css"> |
| <link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet"> |
| <link href="/css/main.css" rel="stylesheet"> |
| <link href="/css/custom.css" rel="stylesheet"> |
| <link href="/css/syntax.css" rel="stylesheet"> |
| |
| <script src="//code.jquery.com/jquery-1.11.0.min.js"></script> |
| <script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script> |
| <script type="text/javascript" src="/js/community.js"></script> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ |
| /* We explicitly disable cookie tracking to avoid privacy issues */ |
| _paq.push(['disableCookies']); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| (function() { |
| var u="//analytics.apache.org/"; |
| _paq.push(['setTrackerUrl', u+'matomo.php']); |
| _paq.push(['setSiteId', '41']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| </head> |
| <body> |
| |
| <a href="https://github.com/apache/struts" class="github-ribbon"> |
| <img decoding="async" loading="lazy" style="position: absolute; right: 0; border: 0;" width="149" height="149" src="https://github.blog/wp-content/uploads/2008/12/forkme_right_red_aa0000.png?resize=149%2C149" class="attachment-full size-full" alt="Fork me on GitHub" data-recalc-dims="1"> |
| </a> |
| |
| <header> |
| <nav> |
| <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"> |
| Menu |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a> |
| </div> |
| <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> |
| </a> |
| <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-2023.html">Announcements</a></li> |
| <li><a href="http://www.apache.org/licenses/">License</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy Policy</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Support<b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu"> |
| <li><a href="/mail.html">User Mailing List</a></li> |
| <li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li> |
| <li><a href="/security.html">Reporting Security Issues</a></li> |
| <li><a href="/commercial-support.html">Commercial Support</a></li> |
| <li class="divider"></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li> |
| <li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">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> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Documentation<b class="caret"></b> |
| </a> |
| <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="https://cwiki.apache.org/confluence/display/WW/Home">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="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li> |
| <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a data-toggle="dropdown" href="#" class="dropdown-toggle"> |
| Contributing<b class="caret"></b> |
| </a> |
| <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 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/">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="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li> |
| <li><a href="/updating-website.html">Updating the website</a></li> |
| </ul> |
| </li> |
| <li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </nav> |
| </header> |
| |
| |
| <article class="container"> |
| <section class="col-md-12"> |
| <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/contributors/documentation-style-guide.md" 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> |
| </ul> |
| |
| <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> |
| |
| <ul> |
| <li>Say it all</li> |
| <li>Say it once</li> |
| <li>Say it well</li> |
| </ul> |
| |
| <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> |
| |
| <ul> |
| <li>Java</li> |
| <li>Javadoc</li> |
| <li>HTML</li> |
| <li>XML</li> |
| </ul> |
| |
| <h2 id="general-punctuation-and-grammar">General Punctuation and Grammar</h2> |
| |
| <p>Good online resources for punctuation, grammar, and text style include</p> |
| |
| <ul> |
| <li><a href="https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style">Wikipedia Manual of Style</a></li> |
| </ul> |
| |
| <p>In print, two excellent (and inexpensive!) resources are</p> |
| |
| <ul> |
| <li><a href="https://www.amazon.com/exec/obidos/tg/detail/-/020530902X/apachesoftwar-20/">The Elements of Style</a></li> |
| <li><a href="https://www.amazon.com/exec/obidos/tg/detail/-/0465004881/apachesoftwar-20/">Associated Press Stylebook</a></li> |
| </ul> |
| |
| <p>Also excellent, but more expensive:</p> |
| |
| <ul> |
| <li><a href="https://www.chicagomanualofstyle.org/">Chicago Manual of Style</a></li> |
| </ul> |
| |
| <h2 id="quick-tips">Quick Tips</h2> |
| |
| <ul> |
| <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”. |
| <ul> |
| <li>Ask yourself: “This what?”</li> |
| </ul> |
| </li> |
| <li>References to other wiki pages can be unqualified. For example: “See .”</li> |
| </ul> |
| |
| <h2 id="dont-be-smurfy">Don’t be smurfy!</h2> |
| |
| <p>A lot of API members use the term “action”. We have</p> |
| |
| <ul> |
| <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> |
| </ul> |
| |
| <p>Here are some terms that can be used to help clarify which action is which.</p> |
| |
| <ul> |
| <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> |
| </ul> |
| |
| <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> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>FIXME</th> |
| <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> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>TODO</td> |
| <td>A page that is incomplete. Try to complete these pages before tagging a distribution</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <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="language-plaintext highlighter-rouge">h2</code> to a <code class="language-plaintext highlighter-rouge">h4</code>.</p> |
| |
| <blockquote> |
| <p>If you find yourself writing too many h2 headings in a single page, consider breaking the page into child pages.</p> |
| </blockquote> |
| |
| <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="language-plaintext highlighter-rouge">Monospaced</code> should be used to files, tags, and methods, like <code class="language-plaintext highlighter-rouge">struts.xml</code>, <code class="language-plaintext highlighter-rouge"><xmltag /></code>, and <code class="language-plaintext 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="language-plaintext highlighter-rouge">-</code> notation.</p> |
| |
| <p>Ordered list should be used when numbering the items is important. Otherwise, prefer unordered lists.</p> |
| |
| <ul> |
| <li>This is an unordered list in star notation;</li> |
| <li>Items can have sub-items |
| <ul> |
| <li>That can have sub-items |
| <ul> |
| <li>That can have sub-items … |
| <ul> |
| <li>What is the limit?</li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li>Mixing ordered and unordered lists is possible: |
| <ol> |
| <li>One;</li> |
| <li>Two;</li> |
| <li>Three.</li> |
| </ol> |
| </li> |
| </ul> |
| |
| <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>Example:</p> |
| |
| <p><img src="http://struts.apache.org/images/struts-power.gif" alt="http://struts.apache.org/images/struts-power.gif" /></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> |
| |
| <table> |
| <thead> |
| <tr> |
| <th>File</th> |
| <th>Optional</th> |
| <th>Location (relative to webapp)</th> |
| <th>Purpose</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><code class="language-plaintext highlighter-rouge">web.xml</code></td> |
| <td>no</td> |
| <td>/WEB-INF/</td> |
| <td>Web deployment descriptor to include all necessary WebWork components</td> |
| </tr> |
| <tr> |
| <td><code class="language-plaintext highlighter-rouge">struts.xml</code></td> |
| <td>no</td> |
| <td>/WEB-INF/classes/</td> |
| <td>Main configuration, contains result/view types, action mappings, interceptors, and so forth</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h2 id="advanced-formatting">Advanced Formatting</h2> |
| |
| <p>Try to specify the language for ``` … ``` blocks.</p> |
| |
| <p><strong>HelloWorld.java</strong></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="nc">String</span><span class="o">[]</span> <span class="n">args</span><span class="o">)</span> <span class="o">{</span> |
| <span class="nc">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> |
| </code></pre></div></div> |
| |
| <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="language-plaintext highlighter-rouge">$</code> should be used to represent a system prompt.</p> |
| |
| <p><strong>Compiling and Running Hello World</strong></p> |
| |
| <div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>$ javac HelloWorld.java |
| |
| $ java HelloWorld |
| Hello, World! |
| </code></pre></div></div> |
| |
| <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> |
| |
| </section> |
| </article> |
| |
| |
| <footer class="container"> |
| <div class="col-md-12"> |
| Copyright © 2000-2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are |
| trademarks of The Apache Software Foundation. All Rights Reserved. |
| </div> |
| <div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div> |
| </footer> |
| |
| <script>!function (d, s, id) { |
| var js, fjs = d.getElementsByTagName(s)[0]; |
| if (!d.getElementById(id)) { |
| js = d.createElement(s); |
| js.id = id; |
| js.src = "//platform.twitter.com/widgets.js"; |
| fjs.parentNode.insertBefore(js, fjs); |
| } |
| }(document, "script", "twitter-wjs");</script> |
| <script src="https://apis.google.com/js/platform.js" 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); |
| js.id = id; |
| js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1"; |
| fjs.parentNode.insertBefore(js, fjs); |
| }(document, 'script', 'facebook-jssdk'));</script> |
| |
| |
| </body> |
| </html> |
