Uploaded image for project: 'DSpace'
  1. DSpace
  2. DS-1638

DSpace 4 Documentation Hierarchy

    Details

    • Type: Improvement
    • Status: Closed (View Workflow)
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: 4.0
    • Fix Version/s: 4.0
    • Component/s: Documentation
    • Labels:
      None
    • Attachments:
      0
    • Comments:
      9
    • Documentation Status:
      Complete or Committed

      Description

      In last night's developers meeting there was a consensus that the current hierarchical structure of the DSpace 3 documentation is not optimal.

      As a first step towards improvement it was agreed that the following separation would have a better chance of sending people faster to the right page in the documentation browsing tree:

      • Using DSpace: ways in which a repository administrator can use, configure and customize DSpace once it's running and functioning properly
      • System Administration: all documentation related to getting DSpace up and running properly. This includes installation, upgrading, troubleshooting and various maintenance tasks.

      Similar to all changes and improvements in DSpace, your feedback and insights on this are appreciated and considered very valuable.

      The transcripts of yesterday's developer meeting can be found here:
      http://irclogs.duraspace.org/index.php?date=2013-08-21

        Attachments

          Activity

          Hide
          bram Bram Luyten (Atmire) added a comment -

          A first attempt was initiated and can be consulted here: https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation

          Originally, all pages were located under the top level page "DSpace System Documentation"
          Two new top level pages were created: Using DSpace and System administration.

          Most of the existing pages have already been moved either to Using Dspace or System Administration. The ones left under "DSpace System Documentation" are those where it wasn't entirely clear to me where they belonged. Up for discussion.

          A few other things that have been done:

          • The table of contents on the front page in DSDOC3X was configured to a depth of 3. I now changed this to a depth of 2 as an attempt to make the list shorter and provide a better overview.
          • Pages related to "ingesting content and metadata" were grouped together under a page with this name, as part of "using dspace"
          • The pages Managing Usage Statistics and Elastic Search Usage Statistics are now grouped under DSpace Statistics
          • The pages Appendix A and Appendix B were given more meaningful names, "Ant targets and options" and "Metadata and Bitstream Format Registries". They were moved and the top level page "appendices" has been deleted.
          • The page "DSpace Service Manager" was moved under Advanced Customization. I'm not very happy about this right now but can't think of a better place to put it at this point.
          • The page "Configuration" used to have a great deal of sub pages about different areas of dspace functionality. Most of these pages have been moved directly under "Using DSpace". The page configuration itself was renamed to "Configuration Reference" to reflect that it needs to become a place where you can find info on any configuration property (dspace.cfg + functionality specific .cfg files)

          Probably forgetting a few minor edits here. Feedback welcome!

          Show
          bram Bram Luyten (Atmire) added a comment - A first attempt was initiated and can be consulted here: https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation Originally, all pages were located under the top level page "DSpace System Documentation" Two new top level pages were created: Using DSpace and System administration. Most of the existing pages have already been moved either to Using Dspace or System Administration. The ones left under "DSpace System Documentation" are those where it wasn't entirely clear to me where they belonged. Up for discussion. A few other things that have been done: The table of contents on the front page in DSDOC3X was configured to a depth of 3. I now changed this to a depth of 2 as an attempt to make the list shorter and provide a better overview. Pages related to "ingesting content and metadata" were grouped together under a page with this name, as part of "using dspace" The pages Managing Usage Statistics and Elastic Search Usage Statistics are now grouped under DSpace Statistics The pages Appendix A and Appendix B were given more meaningful names, "Ant targets and options" and "Metadata and Bitstream Format Registries". They were moved and the top level page "appendices" has been deleted. The page "DSpace Service Manager" was moved under Advanced Customization. I'm not very happy about this right now but can't think of a better place to put it at this point. The page "Configuration" used to have a great deal of sub pages about different areas of dspace functionality. Most of these pages have been moved directly under "Using DSpace". The page configuration itself was renamed to "Configuration Reference" to reflect that it needs to become a place where you can find info on any configuration property (dspace.cfg + functionality specific .cfg files) Probably forgetting a few minor edits here. Feedback welcome!
          Hide
          bram Bram Luyten (Atmire) added a comment -

          Thinking more about this and comparing with other projects, I'm now convinced that the installation and upgrade pages should have more prominent visibility. also moving them to the top level of the tree.

          The section that had "leftover" pages, e.g. "DSpace System Documentation" has been renamed to "DSpace Reference" and moved to the bottom of the tree.

          See:
          https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation

          Show
          bram Bram Luyten (Atmire) added a comment - Thinking more about this and comparing with other projects, I'm now convinced that the installation and upgrade pages should have more prominent visibility. also moving them to the top level of the tree. The section that had "leftover" pages, e.g. "DSpace System Documentation" has been renamed to "DSpace Reference" and moved to the bottom of the tree. See: https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation
          Hide
          bram Bram Luyten (Atmire) added a comment -

          Bringing the upgrade page to the top level of the tree created clutter on the documentation homepage, listing all the pages for upgrading older versions of DSpace. Added a new page in the tree "upgrading older versions of DSpace" containing everything below 1.7.

          Renames:
          "Installation" -> Installing DSpace (better retrieval through search engines as these words are exposed in the URL)
          "Upgrade a DSpace Installation" -> Upgrading DSpace

          Show
          bram Bram Luyten (Atmire) added a comment - Bringing the upgrade page to the top level of the tree created clutter on the documentation homepage, listing all the pages for upgrading older versions of DSpace. Added a new page in the tree "upgrading older versions of DSpace" containing everything below 1.7. Renames: "Installation" -> Installing DSpace (better retrieval through search engines as these words are exposed in the URL) "Upgrade a DSpace Installation" -> Upgrading DSpace
          Hide
          tdonohue Tim Donohue added a comment - - edited

          Hi Bram,

          Great work! I love what you are doing to reorg the docs. A few minor things that are out-of-place / missing:

          1. The "Preface" is now buried under "DSpace Reference". I think this still needs to be at the beginning (could be renamed though), since it's where we detail the overall release and acknowledge who was involved.

          2. Similarly, the old "Introduction" is buried under "DSpace Reference". It could potentially stay there but may need renaming (perhaps "Overview"?)

          3. One bigger point: we need to keep in mind that eventually we'll want to create a PDF from these Wiki Docs. In past releases, we always created the PDF from the "DSpace System Documentation" page which was a parent of all other pages (e.g. https://wiki.duraspace.org/display/DSDOC3x/DSpace+System+Documentation ). However, with the reorg, the only root "parent" page is the https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation homepage. The problem is that if we currently generate the PDF from that page, we'll end up with contents of that page also appearing in the PDF (even the "Recently Updated" box). So the PDF looks a big odd. As I see it, there are two options:
          (a) Either recreate a parent page which is essentially just a Table of Contents (like the old "DSpace System Documentation" page)
          (b) OR, we rework the homepage so that it actually could be included in the final PDF. We'd likely need to remove the "Recently Updated" section and do some other minor cleanup.

          Hopefully #3 isn't too confusing. You can see what I mean simply by generating a PDF following the instructions at: https://wiki.duraspace.org/display/DSDOC/How+To+Export+Downloadable+Docs+from+Wiki#HowToExportDownloadableDocsfromWiki-HowtoGeneratePDFversionofDocumentation

          Show
          tdonohue Tim Donohue added a comment - - edited Hi Bram, Great work! I love what you are doing to reorg the docs. A few minor things that are out-of-place / missing: 1. The "Preface" is now buried under "DSpace Reference". I think this still needs to be at the beginning (could be renamed though), since it's where we detail the overall release and acknowledge who was involved. 2. Similarly, the old "Introduction" is buried under "DSpace Reference". It could potentially stay there but may need renaming (perhaps "Overview"?) 3. One bigger point: we need to keep in mind that eventually we'll want to create a PDF from these Wiki Docs. In past releases, we always created the PDF from the "DSpace System Documentation" page which was a parent of all other pages (e.g. https://wiki.duraspace.org/display/DSDOC3x/DSpace+System+Documentation ). However, with the reorg, the only root "parent" page is the https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation homepage. The problem is that if we currently generate the PDF from that page, we'll end up with contents of that page also appearing in the PDF (even the "Recently Updated" box). So the PDF looks a big odd. As I see it, there are two options: (a) Either recreate a parent page which is essentially just a Table of Contents (like the old "DSpace System Documentation" page) (b) OR, we rework the homepage so that it actually could be included in the final PDF. We'd likely need to remove the "Recently Updated" section and do some other minor cleanup. Hopefully #3 isn't too confusing. You can see what I mean simply by generating a PDF following the instructions at: https://wiki.duraspace.org/display/DSDOC/How+To+Export+Downloadable+Docs+from+Wiki#HowToExportDownloadableDocsfromWiki-HowtoGeneratePDFversionofDocumentation
          Hide
          helix84 Ivan Masár added a comment -

          ad 3.: It would be even better to keep the dynamic content in, but mark it up as not printable. I'm sure there must be several ways how to do that, including macros and confluencedefaultpdf.css.

          https://confluence.atlassian.com/display/DOC/NoPrint+Example+of+a+User+Macro
          http://docs.servicerocket.com/display/AtlassianPlugins/show-if

          Show
          helix84 Ivan Masár added a comment - ad 3.: It would be even better to keep the dynamic content in, but mark it up as not printable. I'm sure there must be several ways how to do that, including macros and confluencedefaultpdf.css. https://confluence.atlassian.com/display/DOC/NoPrint+Example+of+a+User+Macro http://docs.servicerocket.com/display/AtlassianPlugins/show-if
          Hide
          bram Bram Luyten (Atmire) added a comment -

          1 & 2: you're right: the contents in introduction, preface and functional overview should be easy to access for people who are new and should belong up higher. I moved Introduction to the top level and currently attached Preface and Functional overview as sub pages.

          I do have a problem with "Preface", from what it contains, it really mainly lists the release notes of the latest version. The list of contributors also only seems to apply to the latest version. So why not rename the page DSpace 4X Release notes?

          3. You're right, the PDF generation process should still remain intact. I guess I'm more a fan of your (a) option. This could be the Introduction page for example if we add the entire contents below.

          Show
          bram Bram Luyten (Atmire) added a comment - 1 & 2: you're right: the contents in introduction, preface and functional overview should be easy to access for people who are new and should belong up higher. I moved Introduction to the top level and currently attached Preface and Functional overview as sub pages. I do have a problem with "Preface", from what it contains, it really mainly lists the release notes of the latest version. The list of contributors also only seems to apply to the latest version. So why not rename the page DSpace 4X Release notes? 3. You're right, the PDF generation process should still remain intact. I guess I'm more a fan of your (a) option. This could be the Introduction page for example if we add the entire contents below.
          Hide
          tdonohue Tim Donohue added a comment -

          Bram,

          Sounds good. I'm fine with all your suggestions.

          One note about renaming the "Preface". I'd rather just call it generically "Release Notes" (so we don't have to constantly rename the page for each release). One minor warning is that we also have the informal release notes also at: https://wiki.duraspace.org/display/DSPACE/DSpace+Release+4.0+Notes . But, since the contents of these pages is similar anyways, hopefully that won't be a big deal.

          Show
          tdonohue Tim Donohue added a comment - Bram, Sounds good. I'm fine with all your suggestions. One note about renaming the "Preface". I'd rather just call it generically "Release Notes" (so we don't have to constantly rename the page for each release). One minor warning is that we also have the informal release notes also at: https://wiki.duraspace.org/display/DSPACE/DSpace+Release+4.0+Notes . But, since the contents of these pages is similar anyways, hopefully that won't be a big deal.
          Hide
          bram Bram Luyten (Atmire) added a comment -

          I just updated the "Preface" page and processed the renaming to "Release Notes"
          https://wiki.duraspace.org/display/DSDOC4x/Release+Notes

          Tim, can you still followup on the issue of PDF "printability" and Ivan's suggestion of marking dynamic content as not printable?

          There are other documentation details to tackle, but I think we managed to rework the hierarchy, so I'd be in favor of closing this ticket and following up other issues (including printability) in more specific JIRA tickets.

          Show
          bram Bram Luyten (Atmire) added a comment - I just updated the "Preface" page and processed the renaming to "Release Notes" https://wiki.duraspace.org/display/DSDOC4x/Release+Notes Tim, can you still followup on the issue of PDF "printability" and Ivan's suggestion of marking dynamic content as not printable? There are other documentation details to tackle, but I think we managed to rework the hierarchy, so I'd be in favor of closing this ticket and following up other issues (including printability) in more specific JIRA tickets.
          Hide
          tdonohue Tim Donohue added a comment -

          Bram,

          I've updated the content on the DSpace 4.x Documentation homepage to be excluded from the exported PDF. It's done via a "Scroll PDF Exporter Ignore" macro, which now surrounds all content on this page:

          https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation

          I've also done a test PDF export today – and it looks great. So no more needs to be done (as far as I can see).

          Finally, I've updated our own docs on how to export docs to PDF based on these changes: https://wiki.duraspace.org/display/DSDOC/How+To+Export+Downloadable+Docs+from+Wiki

          All in all, I think this is looking great. Closing this ticket as "fixed". Any other specific doc issues can be opened in separate tickets.

          Show
          tdonohue Tim Donohue added a comment - Bram, I've updated the content on the DSpace 4.x Documentation homepage to be excluded from the exported PDF. It's done via a "Scroll PDF Exporter Ignore" macro, which now surrounds all content on this page: https://wiki.duraspace.org/display/DSDOC4x/DSpace+4.x+Documentation I've also done a test PDF export today – and it looks great. So no more needs to be done (as far as I can see). Finally, I've updated our own docs on how to export docs to PDF based on these changes: https://wiki.duraspace.org/display/DSDOC/How+To+Export+Downloadable+Docs+from+Wiki All in all, I think this is looking great. Closing this ticket as "fixed". Any other specific doc issues can be opened in separate tickets.

            People

            • Assignee:
              bram Bram Luyten (Atmire)
              Reporter:
              bram Bram Luyten (Atmire)
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: