Versions Compared

Old Version 1

changes.mady.by.user Mike Conlon

Saved on

compared with

New Version 2

changes.mady.by.user Mike Conlon

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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, also known as the project wiki, also known as the community wiki)

  • Located at http://wiki.duraspace.org/display/VIVO

  • The main wiki holds all sorts of information, as it does now.
  • Includes governance, task forces, interest groups, background material, community support materials
  • Does not include release specific information describing the product

VIVO Release specific wikis, also known as the documentation

  • 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/VIVOARCHIVEin release specific wikis.  These wikis will be copied forward to create spaces for new releases.  The next release wiki will be available before the release of the software to document the next release.
  • 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

...

  • The styling indicates that the wiki id documentation for a specific release
  • Release specific wikis exist for releases prior to the current release, for the current release and for the next release
  • The release specific wikis use a documentation template and a documentation PDF export template optimized for the production of a single PDF document from the documentation wiki.

Minimal 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

Image Removed

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

  • The Git README.md refers to the project wiki and the release specific wiki

Between releases

  • All community processes continue in the project wiki
  • Documentation specific wikis are available for improvement
  • A next release wiki is created from the current release wiki when there are new features to document.
children