This is an automated email from the ASF dual-hosted git repository.
git-site-role pushed a commit to branch asf-staging
in repository https://gitbox.apache.org/repos/asf/struts-site.git
The following commit(s) were added to refs/heads/asf-staging by this push:
new 0a6517a Updates stage by Jenkins
0a6517a is described below
commit 0a6517a685f05e0cbc4b2bb317304ee0a5c7c5ae
Author: jenkins <[email protected]>
AuthorDate: Thu Oct 1 18:52:46 2020 +0000
Updates stage by Jenkins
---
.../contributors/documentation-style-guide.html | 460 +++++++++++++++++++++
.../{index.html => editing-the-documentation.html} | 75 ++--
content/contributors/index.html | 12 +-
3 files changed, 499 insertions(+), 48 deletions(-)
diff --git a/content/contributors/documentation-style-guide.html
b/content/contributors/documentation-style-guide.html
new file mode 100644
index 0000000..258450c
--- /dev/null
+++ b/content/contributors/documentation-style-guide.html
@@ -0,0 +1,460 @@
+<!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="/highlighter/github-theme.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>
+</head>
+<body>
+
+<a href="http://github.com/apache/struts"; class="github-ribbon">
+ <img style="position: absolute; right: 0; border: 0;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png";
alt="Fork me on GitHub">
+</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.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>
+ </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 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><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="https://cwiki.apache.org/confluence/display/WW/Contributors+Guide";>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="highlighter-rouge">h2</code> to a
<code class="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="highlighter-rouge">Monospaced</code> should be used to files,
tags, and methods, like <code class="highlighter-rouge">struts.xml</code>,
<code class="highlighter-rouge"><xmltag /></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>
+
+<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="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="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="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>
+</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="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 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-2018 <a href="http://www.apache.org/";>The Apache
Software Foundation </a>.
+ All Rights Reserved.
+ </div>
+ <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>
+ <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>
diff --git a/content/contributors/index.html
b/content/contributors/editing-the-documentation.html
similarity index 73%
copy from content/contributors/index.html
copy to content/contributors/editing-the-documentation.html
index 2c4db64..eeb956e 100644
--- a/content/contributors/index.html
+++ b/content/contributors/editing-the-documentation.html
@@ -7,7 +7,7 @@
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
- <title>Contributors Guide</title>
+ <title>Editing the Documentation</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">
@@ -127,59 +127,58 @@
<article class="container">
<section class="col-md-12">
- <a class="edit-on-gh"
href="https://github.com/apache/struts-site/edit/master/source/contributors/index.md";
title="Edit this page on GitHub">Edit on GitHub</a>
+ <a class="edit-on-gh"
href="https://github.com/apache/struts-site/edit/master/source/contributors/editing-the-documentation.md";
title="Edit this page on GitHub">Edit on GitHub</a>
- <h1 id="contributors-guide">Contributors Guide</h1>
-
-<h2 id="source">Source</h2>
+ <a href="index.html" title="back to Contributors Guide"><< back to
Contributors Guide</a>
+
+ <h1 class="no_toc" id="editing-the-documentation">Editing the
Documentation</h1>
-<ul>
- <li><a href="building-the-framework-from-source">Building the Framework from
Source</a>
- <ul>
- <li><a href="building-with-maven">Building with Maven</a></li>
- </ul>
- </li>
- <li><a href="creating-and-signing-a-distribution">Creating and Signing a
Distribution</a></li>
- <li><a href="precise-error-reporting">Precise Error Reporting</a></li>
- <li><a href="obtaining-an-idea-license">Obtaining an IDEA license</a></li>
- <li><a
href="https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html";>How
to Write Doc Comments for the Javadoc Tool</a> (Oracle)</li>
+<ul id="markdown-toc">
+ <li><a href="#documentation-workflow"
id="markdown-toc-documentation-workflow">Documentation Workflow</a></li>
</ul>
-<h2 id="documentation">Documentation</h2>
+<p>Changes to the documentation can be requested to the <a
href="https://issues.apache.org/struts/secure/Dashboard.jspa";>issue
tracker</a>,
+or created via Pull Requests to the Github <a
href="https://github.com/apache/struts-site";>repository</a>. You can notice a
button
+in the upper left corner labeled <code class="highlighter-rouge">Edit on
GitHub</code> which helps you create changes to the docs.</p>
-<ul>
- <li><a href="#PAGE_27087">Editing the Documentation</a></li>
- <li><a href="#PAGE_13822">Documentation Colophon</a></li>
- <li><a href="#PAGE_14055">Documentation Style Guide</a></li>
-</ul>
+<p>The Struts 2 Documentation space is bundled with the Struts distribution,
and, eventually, the content may be checked
+into an ASF repository. Accordingly, all volunteers working to this space must
have a CLA on file.</p>
-<h2 id="licensing-and-copyright">Licensing and Copyright</h2>
+<p>The project also hosts a second Confluence space, the <a
href="http://cwiki.apache.org/S2WIKI/home.html";>Struts 2 wiki</a>,
+which can be edited by anyone who creates an account.</p>
-<ul>
- <li><a href="http://people.apache.org/~cliffs/3party.html";>Third Party
Licensing Policy RFC</a></li>
- <li><a href="http://www.apache.org/legal/src-headers.html";>ASF Source Header
and Copyright Notice Policy</a></li>
- <li><a href="http://tinyurl.com/mw7t6";>Author Tags</a></li>
-</ul>
+<p>See also: <a href="../helping">How to Help FAQ</a>.</p>
+
+<h2 id="documentation-workflow">Documentation Workflow</h2>
-<h2 id="quick-links">Quick Links</h2>
+<p>Since projects like Struts wear our code “on our sleeve”, there’s always a
discussion over whether the website should
+represent the latest documentation or the documentation for the “best
available” release. Over the years, we’ve done it
+one way and the another, and now we do it both ways :-)</p>
<ul>
- <li><a href="../../helping">How to Help FAQ</a></li>
- <li><a href="../../bylaws">Project Charter</a></li>
- <li><a href="../../volunteers">Volunteers</a></li>
- <li><a href="../../releases">Release Guidelines</a></li>
- <li><a href="http://people.apache.org/~mrdon/action2-api/";>Javadocs</a></li>
- <li><a href="https://svn.apache.org/repos/asf/struts/action2";>Source code
repository</a></li>
- <li><a
href="http://today.java.net/pub/a//today/2005/02/25/opensymphony.html";>Our
WebWork roots</a></li>
+ <li><a
href="http://cwiki.apache.org/WW/home.html";>http://cwiki.apache.org/WW/home.html</a></li>
</ul>
-<h2 id="bleeding-edge">Bleeding Edge</h2>
+<p>When we vote a test build to a release (of any flavor: alpha, beta, GA), we
archive the HTML version of the documentation
+for future reference. When a release is designated GA, we update the
appropriate links on the main site to point
+to the archival copy.</p>
+
+<p>Since we bundle the HTML version of the documentation with the release, we
require authors to file a CLA, to ensure that
+we actually have distribution rights.</p>
+
+<p>To cover all the bases, we also maintain a “community wiki”, that is not
bundled with the distribution.</p>
<ul>
- <li><a href="http://wiki.apache.org/struts/StrutsActionRelease202";>Struts
2.0.2 Release Plan</a></li>
- <li><a href="http://wiki.apache.org/struts/StrutsTi";>Struts Ti
Proposal</a></li>
+ <li><a
href="http://cwiki.apache.org/S2WIKI/home.html";>http://cwiki.apache.org/S2WIKI/home.html</a></li>
</ul>
+<p>It’s open to anyone who signs up for an account on Confluence. Sometimes,
we do move documentation from the community wiki
+to the documentation wiki, if the author can a CLA.</p>
+
+<p>Sadly, not everyone can file a CLA. Many organizations still use aggressive
IP agreement that assign rights to our every
+stray thought to the company, 24/7. In fact, some organizations grant a
special dispensation for the ASF so that their
+employees can file CLAs.</p>
+
</section>
</article>
diff --git a/content/contributors/index.html b/content/contributors/index.html
index 2c4db64..451d2fb 100644
--- a/content/contributors/index.html
+++ b/content/contributors/index.html
@@ -148,9 +148,8 @@
<h2 id="documentation">Documentation</h2>
<ul>
- <li><a href="#PAGE_27087">Editing the Documentation</a></li>
- <li><a href="#PAGE_13822">Documentation Colophon</a></li>
- <li><a href="#PAGE_14055">Documentation Style Guide</a></li>
+ <li><a href="editing-the-documentation">Editing the Documentation</a></li>
+ <li><a href="editing-the-documentation">Documentation Style Guide</a></li>
</ul>
<h2 id="licensing-and-copyright">Licensing and Copyright</h2>
@@ -173,13 +172,6 @@
<li><a
href="http://today.java.net/pub/a//today/2005/02/25/opensymphony.html";>Our
WebWork roots</a></li>
</ul>
-<h2 id="bleeding-edge">Bleeding Edge</h2>
-
-<ul>
- <li><a href="http://wiki.apache.org/struts/StrutsActionRelease202";>Struts
2.0.2 Release Plan</a></li>
- <li><a href="http://wiki.apache.org/struts/StrutsTi";>Struts Ti
Proposal</a></li>
-</ul>
-
</section>
</article>
![https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"](https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"){kind=link}
![http://struts.apache.org/images/struts-power.gif"](http://struts.apache.org/images/struts-power.gif"){kind=link}