Old Release

This documentation relates to an old version of VIVO, version 1.9.x. Looking for another version? See all documentation.

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

 

Goals

Recognize that some documentation applies only to a particular release, or set of releases.

Recognize that documentation will most likely be found by web searches, not by walking the wiki.

Information about the current release should be the easiest to find.

Information about older releases should be available somewhere.

There should be an area for documenting new features before they are included in a release.

It should be easy to tell whether the information you are viewing is correct for the code you are using.

Documentation should not be frozen at release time - It should remain available for improvements.

The most basic instructions should be included in the release.

Novice users should be able to find what they need; expert users should be able to find more

Two types of wiki pages

Release-specific pages

  • Apply to a specific release, or range of releases.
  • Incorrect if used with an inappropriate release.
  • Examples: installation instructions, customization guides, ontology details

Release-neutral pages

  • Equally relevant to all releases (or to none)
  • Examples: tutorials, meeting agendas, glossary, outreach events and resources, presentations.
  • Most wiki pages are not release specific

Approach

Three Confluence spaces for documentation

VIVO (main wiki)

  • Located at http://wiki.duraspace.org/display/VIVO
  • The main wiki holds all sorts of information, as it does now.
  • The release-specific information will be collected under the heading of "VIVO Documentation".
    • Here is a mock-up of what this page might look like.

VIVO Archive

  • Located at http://wiki.duraspace.org/display/VIVOARCHIVE
  • Contains release-specific pages for older releases.
  • Separate sections for each archived release.
  • Something in the styling should indicate that this is not the main wiki
    • When pages are copied from the main wiki, they acquire that styling auto-magically

VIVO Next Release

  • Located at http://wiki.duraspace.org/display/VIVONEXT
  • Contains pre-release pages for the next release
  • Something in the styling should indicate that this is not the main wiki
    • When pages are copied to the main wiki, they acquire the styling of the main wiki

Divide release-specific pages into Document trees

  • Examples:
    • Installation Instructions
    • Upgrade Instructions
    • Customization Guide
    • Data Ingest Guide
    • Ontology Reference
    • Programmer's Notes
  • Take advantage of Confluence's ability to export an entire page tree as a PDF.
  • Export PDF documents as part of the release process
    • The release distribution will include install.pdf and upgrade.pdf
      • Perhaps others?
    • There should still be a link to the "VIVO Documentation" page of the wiki
      • Improvements might be made after the release

No documentation in the Git repository

  • The wiki becomes the definitive source of documentation
  • Remove [VIVO]/doc/install.html, [VIVO]/doc/upgrade.html
  • Create [VIVO]/doc/install.txt, with a link to the "VIVO Documentation" page in the wiki.
    • Perhaps additional references for other documents

The release process

Example: release 1.9

  • Copy the existing documents to the archive
    • These apply to release 1.8
    • Create an area for release 1.8 in the archive
    • Copy the document page trees from the main wiki
  • Merge the changes to the documents for release 1.9
    • Merge additions and modifications from the “next release” space.
    • This process will not be automated.
      • Each addition must be placed at the correct place in the tree.
      • Changes to individual pages may require merging or replacing
      • "Next release" may have a page saying "this page deleted in 1.9"
  • Clear the "Next Release" area

Between releases

  • Enhance the current documents
    • Create new pages in the main wiki space
    • Correct problems in the main wiki space
  • Enhance the archived documents, if desired
  • Populate the “next release” space
    • Create new pages
    • Modify existing pages
      • Either by creating a copy and modifying, or by stating how the new page should differ from the existing one
    • Delete existing pages
      • By creating a "next release" page that says only "This page goes away" or equivalent
    • Remember that:
      • People who are working from the GitHub develop branch may use the "next release" pages
      • The merge from "next release" will be done by a person. Leave instructions, and assume some intelligence in the person who does the merge.

The Documentation page - a mockup

  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.