Documentation Wiki Spaces Overview

Each major version of DSpace has its own Wiki Space.

• Space ID: Each DSpace Documentation space has a "Space ID" of the following format: "DSDOCxx" (where 'xx' represents the version of DSpace)
  • e.g. For 3.x, the docs are in DSDOC3x.
  • e.g. For 4.x, the docs are in DSDOC4x 
• General Space: The DSDOC (generic) space is used to inform people of all available DSpace Documentation, e.g. All Documentation, as well as provide a central place for these internal Documentation Management notes.
• Space Header: Each DSpace Documentation space also has a header (see Documentation Space Headers below) which lets users know if it refers to an old, current or unreleased version of the software.
• Shared Left Sidebar: The Left Sidebar on all Documentation Spaces is identical – it just loads the _DocLeftSidebar reusable content page. This is very powerful as it means that the sidebar on all existing Spaces can be edited from a single location.
  • Note: If you view the Wiki source, you'll notice that the _DocLeftSidebar actually assigns CSS classes to each Documentation link in the "All Documentation" list. This is so that each Documentation Space can have a custom CSS style which makes its listing appear bold when you are in that Space. For an example, see the DSDOC3x, and DSDOC4x spaces – notice how different items in that listing are bolded. This is a custom CSS style enabled for each Space.

Copying Existing Docs to a New Space

In order to prepare for the next release, you obviously need to begin Unreleased Documentation early. The easiest way to do this is to generate a new Documentation Space for that unreleased version, and copy the latest Documentation over to that space. 

Here's the steps:

1. First, you need to login as an Administrative user
2. Visit the Confluence Dashboard, and create a new Space for this new release
   1. Select "Documentation Space" option
   2. Space Name: DSpace #.x Documentation (e.g. "DSpace 8.x Documentation")
   3. Space ID: DSDOC#x (e.g. DSDOC8x for DSpace 8.x documentation) Make sure to follow our recommended Space ID naming conventions as described above.
3. Copy the latest release documentation into this new Space
   1. Go to the latest release documentation homepage (e.g. DSDOC7x)
   2. Select "..." → "Copy" option
   3. Select Destination "Space" to be the newly created Space (from step 2 above)
   4. Select BOTH "Include attached files and images" AND "Include child pages" options.
   5. Click "Next"
   6. Make sure the Preview looks correct (You may need to move the homepage later).  Make sure all options are checked to include labels, attached files & restrictions.
   7. Click "Copy".  This may take a minute or two! The DSpace Documentation is very large.
4. Once the content has been copied to the new Space, visit the new Space.
   1. In the "Space Tools" select "Reorder Pages". 
   2. Make sure the layout looks correct.  Likely the homepage of the old space will be under the (default) homepage of the new space.  If so, drag it out.
      1. E.g. it may look like "New Space Home" > "DSpace 7.x Documentation".  You want to drag the "DSpace 7.x Documentation" to the top level in order to make it the new homepage.
   3. Delete the default homepage of the new space. It is no longer needed once it has no children.
   4. Edit new homepage to match the new version number (e.g. "DSpace 7.x Documentation").  Also make any other necessary minor updates to the homepage
   5. Go to "Space Tools" → "Overview".  Change the "Home page" to be the newly copied content homepage.
   6. The various sections may end up resorted alphabetically. Check the last version and reorder the sections to the proper order (Using "View in Hierarchy" option).
5. Next you'll need to tweak several Space settings to get it formatted similar to the rest of our Documentation. We'll start simple by tweaking the "Space Description"
   • Go to "Space Tools -> Overview" and change the "Description" to have the correct version number (e.g. "Official docs for DSpace 8.x") and click "Save".
6. Now, change the logo for the space
   1. Go to "Space Tools → Configure Sidebar".  Click the edit icon next to the logo, and upload our DSpace logo
7. Now, change the "Documentation Space Header" so that we have the "Unreleased Documentation Header" in place. The full instructions can be found below in the #Documentation Space Headers section.
8. Now, change the Left Sidebar to load up the _DocLeftSidebar shared content (this displays the DSpace logo and list of recent versions). The full instructions can be found below in the #Documentation Shared Sidebar section.
9. Modify the All Documentation wiki page to list this version of the Documentation, and make sure to note that it is UNRELEASED.
10. Let's check/update the Space permissions / access rights
    • Go to "Browse -> Space Admin" and click on "Permissions"
    • On the Permissions page, assign these permissions to these groups:
      • 'confluence-users' group -> "View" and "Add Comments" permissions only
      • 'dspace-committer' group -> Full permissions (select all options, including Admin)
      • 'dspace-docgardener' group -> Full permissions (select all options, including Admin)
11. Finally, to ensure everything was copied properly (and no links were "broken" in the process), you may want to look at these reports:
    • "Orphaned Pages" Report (Go to "Space Tools → Content Tools → Orphaned Pages") : This is a list of all pages in the space which are not being linked to from another page (no incoming links)
    • "Undefined Pages" Report (Go to "Space Tools → Content Tools → Undefined Pages") : This is a list of all broken internal wiki links within the space (and the page the link appears on). Confluence sees a broken link as leading to an "undefined page". Therefore you can use this report to determine if any links are now broken in the Documentation, and fix them appropriately.

Documentation Space Headers

As mentioned above, on each Documentation Space we want to provide users with context information to let them know whether the Documentation they are looking at is current, and also give them information on how to get to current or older documentation (based on the version of DSpace they are using).

Editing Headers:

• Space Headers can be edited only by a Wiki Space Administrator
• Visit "Space Tools → Look and Feel"
• Click on "Sidebar, header and footer"
• You'll see a "Header" field that you can fill out and click "Save"

There are three types of headers we use on Documentation spaces.

Current Documentation Header

This header is used to notify users that the Documentation Space they are visiting is for the current version of DSpace:

What it looks like:

Wiki Source:

{tip:title=Current Release}
This documentation covers the latest release of DSpace, version 5.x. Looking for another version? [See all documentation|DSDOC:All Documentation].
{tip}

Old Documentation Header

This header is used to notify users that they are looking at an old version of the Documentation.

What it looks like:

Wiki Source:

{note:title=Old Release}
This documentation relates to an old version of DSpace, version 4.x. Looking for another version? [See all documentation|DSDOC:All Documentation].
{note}

Unreleased Documentation Header

This header is used to notify users that they are currently viewing documentation for an unreleased version of DSpace.

What it looks like:

Wiki Source:

{warning:title=Unreleased Documentation}
This documentation is unreleased and still in development. *It may describe features which are not yet released in DSpace.* \\ Looking for another version? [See all documentation|DSDOC:All Documentation]
{warning}

Documentation Shared Sidebar

As mentioned above, on each Documentation Space we want to have a shared left sidebar which keeps all our Documentation looking similar in nature and allows users to more easily jump between versions of the Documentation. This shared left sidebar is actually a very simple Wiki page (see _DocLeftSidebar), which we load into the "navigation" section of each of the Documentation spaces.

Editing The Left Sidebar:

• The left sidebar can be edited only by a Wiki Space Administrator
• Visit "Space Tools → Look and Feel"
• Click on "Sidebar, header and footer"

• In the "Sidebar" field, you want to place the following Wiki Markup (which will cause the _DocLeftSidebar wiki page to appear as the sidebar):

  
  

  {include:DSDOC:_DocLeftSidebar} {livesearch:spaceKey=DSDOC7x|placeholder=Search documentation|additional=page excerpt}

  
  

• Click "Save"

• Now, we'll likely want to ensure this version of DSpace is listed in the Sidebar. To do that, just visit the _DocLeftSidebar page, edit it, and add a line similar to the following:

  • Create a new "div" macro (creates a new HTML <div> tag for us)

  • Set Class as "DSDOC7x" (for DSDOC7x space)

  • Set Style as "padding-left: 10px" (to align with all others in the list

  • As the text (inside the "div"): "DSpace 7.x (Unreleased)" (and link it to the DSDOC7x Homepage)

  • NOTE: Obviously you can copy from another "div" macro if these settings change.
• Finally, let's tweak the stylesheet of the Space, so that its listing in the sidebar appears bolded.
  • Go back to the "Space Tools → Look and Feel"
  • Click on "Stylesheet"

  • Click "Edit" and add a style similar to the following (notice that this "div" style matches the "div" macro defined above):

    /** Bold sidebar link to this Space **/ div.DSDOC7x { font-weight:bold; } /** OR by child number **/ /** Bold sidebar link to this Space **/ .custom-sidebar-content > .content > ul > li:nth-child(3) { font-weight:bold; }

    
    

  • Click Save

The final result is that, when you go back to the Space, you'll see that the contents of the _DocLeftSidebar wiki page now appear in the left sidebar. You'll also notice that this Space's name should appear bolded, and when you click on different versions of the Documentation those Space names should appear bolded instead. This allows the sidebar to always be identical across all Documentation Spaces, which makes it easier to manage across all our documentation.

Reusable Content

Reusable content can be found on the ReusableContent child page.