Access Keys:
Skip to content (Access Key - 0)

Notation

Step 5 - Update Documentation

To recap, we have created new version spaces by copying the spaces for a previous version, changed permissions for these new spaces, updated the navigation so that we can easily access the new spaces and pages, and created macros for the new release. We have laid the foundation for updating the documentation for the release. We can now begin to update the documentation in these new spaces so that it is relevant to the new release.

This step will require efforts from multiple individuals both inside and outside the caGrid development team and Knowledge Center. It is also the most time consuming step and will most likely take a few weeks to complete. Therefore, while this step is being completed, you can move on to the next steps (creating new pages and updating links), so that progress on updating the wiki will still be made. Then, as project documentation is updated, you will need to update the links on the pages that will be created in the next step. It should be a continual process of updating documentation, updating links, and reviewing pages, site maps, and navigation so that nothing is missed. Think Agile software development for wikis.

Divide Up the Work

cagrid.org has a LOT of pages and updating the content will take some time. Therefore, all of the pages that need to be updated should be split up and assigned to specific developers or individuals familiar with certain projects. For example, one person will update all of the content for Data Services while another updates the guides for FQP. Tutorials, installation guides, and prerequisite pages will also have to be updated. The main documentation and downloads pages for each project should be updated by you (assuming that since you're reading this, you're in change of updating the wiki). The division of labor is usually coordinated by the KC Operations manager.

I've attempted to identify pages that need to be updated with each release. Below is a partial list of pages that need to be updated. The provided links point to 1.4 pages and are used as example of the pages that need to be updated. You should find the page for the new release (usually in new cagridxx space or projectnamexx) with the same name. There will most likely be pages that have been missed, so use this list only as a guide. You can browse for pages by using the "Site Map" of spaces.

The links below point to pages in 1.4 spaces. Do not change these pages! Be aware of what space you are in and what pages are you editing. Make sure you update the pages only for the new release version, meaning that you want to edit the pages with these titles/page names that are in the new spaces that you creates/copied.

What to Update

Content - An administrator's guide for x.x should refer to features and uses of the service for x.x. Sometimes, the content from the previous version can stay the same, but with a few added paragraphs and changed sentences for the new version. Other times, it will be a completely new guide.

References to old versions - Each document will need to be scanned for any references to a previous version. This may be as simple as changing a "4" to a "5" and ensuring that the change is acceptable in context. Make sure that after a change, the content is still applicable for the new version number.

Links - Update all links to point to the latest version release. A 1.3 page should only contain links for other 1.3 pages or non-version specific pages, a 1.4 page should only contain links for other 1.4 pages or non-version specific pages, etc. This also includes updating all links to javadocs.

Macros - Update all version specific macros. For example, {cagrid-1.4-installer-link} should be changed to {cagrid-x.x-installer-link}, where "x.x" is the latest release number.

Other Pages that May Need to be Updated (but not necessarily)

Sometimes it will be unavoidable to have multiple pages in different version spaces for the same information. For example, "Request a Host Certificate" is in the "knowledgebase" and "knowledgebase14" space and contains identical information.

This occurs when new documentation is updated and contains links to previous version pages. We don't want the new documentation to link to "old" documentation, but rather we want to reference pages for the same, current version. We need a page for that information in the new version spaces, but the information hasn't changed. Hence, the duplication. Try to reduce the amount of duplicate pages whenever possible by using {include} or by referencing non-version specific pages.

There are a number of pages in "knowledgebase" and "knowledgebase14" that are duplicates of each other. This will hopefully be resolved soon by using {include}

Step 4 - Create New Macros Preparing for the Release - Create New Documentation Step 6 - Create Additional Pages
Last edited by
Sarah Honacki (347 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence