The Apache Portals Documentation Effort
This page covers how to contribute to the Apache Portals's documentation.
We are working very hard to improve Apache Portals's documentation.
Below is the list of documentation items we are working on listed in order
of priority from greatest to lowest. We need help with them all!
- Apache Portals Website
The Portals website needs work...
- Jetspeed-2 Website
- The Jetspeed-2 Website needs a lot of work
- Each component needs its own documentation page
- Jetspeed-1 Website Conversion
- Jetspeed-1 Website needs to be converted to Maven
- Add tutorial from Bluesunrise
Our Documentation Has Three States
- Infancy: A document becomes nascent in the Wiki
as an empty or sparsely populated page. At this point, people continue to
add and revise the content until it becomes mostly stable and unchanging.
- Stability: Once the document has reached a stable point, it is converted into the xdoc
format and injected into the portals-site (or subproject) cvs or Subversion modules.
- Maturity: As changes to the projects are made, the documentation
is updated and improved via xdoc patches from the Issue Tracking system.
How You Can Help
Now that you know what we are working on, you need to know the best ways to help.
Content is farmed and stabilized on the Apache Portals Wikis
until it is stable enough to become official documentation. Additionally
questions are answered and re-answered on the mailing lists.
You can help the Documentation effort by:
- Editing The Wiki Content: Mature and stabilize the information on the Wiki.
- Filtering The Mailing List: When you see something float
by on the mailing list that should become part of the official,
please convert it into the appropriate xdoc format and submit it as an
issue in our Issue Tracking system.
- Creating Xdoc Patches: If you find a typo, mistake or
overlooked information in the official documentation, please create
an issue in our Issue Tracking system.
Getting The Documentation Source And Making A Patch
- Get The Source:
Check out the latest source from the Portals Subversion module. You can learn
about the Subversion repositories
in the Version control with Subversion book or in the Subversion FAQ.
The Portals Site documentation resides in the portals site module:
svn checkout http://svn.apache.org/repos/asf/portals/site site
The migration process to Subversion is not (yet) finished. The documentation
of the Jetspeed modules is still under cvs. Follow the jetspeed or jetspeed-2
links on the navigation bar to learn how to get cvs based documentation for
- Build The Site:
The documenation is built using Maven,
with the following command:
Afterwards, you should get something like:
Total time: 20 seconds
You will find the built HTML in $PATH_TO_MODULE/target/docs.
- Make Your Changes:
The docs are written using the Anakia Xdoc format, which you can learn about here.
The source files are found in the $PATH_TO_MODULE/xdocs directory, each xml file corresponding to the generated html file.
Menu information is found in the navigation.xml files.
- Make A Patch:
cvs diff -rNu > name_of_patch.patch
- Submit Your Changes:
We use the JIRA Issue Tracking system to track issues. Once
you have a patch, log in the Issue Tracking System
and create a new issue in the Documentation module. A project committer will approve the patch
and apply it, or let you know if something should be changed.
- Thank you for helping out!
How to Publish the Web Site
This section is for committers on the Portals project.
- Follow the directions above. In summary:
- Check out the source from the SVN Repository.
- Generate the site with Maven.
- Create an issue in JIRA to give the work visibility, if needed.
- Modify the source files, as necessary.
- Re-generate the site as needed to verify your changes.
- Then, in addition:
- Update /www/portals.apache.org
which is on people.apache.org. Make sure the file permissions are group writeable (portals group).
The contents of this directory are replicated to
the live site every 4 hours.
- Commit Your Changes to the SVN Repository.
- Resolve the issue in JIRA, as needed.