The Apache Portals Documentation Effort

Documentation Roadmap

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

  1. 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

              1. 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 those projects.

              2. Build The Site: The documenation is built using Maven, with the following command: 

                maven site:generate

                Afterwards, you should get something like: 

                BUILD SUCCESSFUL
Total time:  20 seconds

                You will find the built HTML in $PATH_TO_MODULE/target/docs.

              3. 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.

                    1. Follow the directions above. In summary:
                      1. Check out the source from the SVN Repository.
                      2. Generate the site with Maven.
                      3. Create an issue in JIRA to give the work visibility, if needed.
                      4. Modify the source files, as necessary.
                      5. Re-generate the site as needed to verify your changes.
                    2. Then, in addition:
                      1. 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.
                      2. Commit Your Changes to the SVN Repository.
                      3. Resolve the issue in JIRA, as needed.