Hyrax Documentation Structure Summary [NEW]

For the purposed structure see Information for documentation creators below. For guidelines around “where to put what?” see Information for documentation creators below.

A. For the Market Segment (Confluence)

1. Hyrax Overview and Core Concepts

2. Features and Capabilities (including Accessibility Compliance)

3. Comparison Guides (Hyrax vs. Other Solutions, PostgreSQL vs. Fedora)

4. Case Studies of Real-World Implementations

5. Implementation Planning Resources

6. Roadmap and Future Development Plans

B. For Repository Administrators (Confluence)

1. Administrative Dashboard Guide

2. User Management

3. Admin Set Management

4. Collection Management

5. Workflow Configuration

6. Theming and Branding

7. Analytics and Reporting

8. Content Display Configuration

   • Viewer Technologies (PDF.js vs. Universal Viewer)

   • IIIF Implementation

     • IIIF Manifests for Works: Any work showing images or media files through the embedded viewer (IIIF viewer) has a IIIF manifest available in JSON format. On the Hyrax demonstration sites, this information can be accessed by adding "/manifest" at the end of the URL (before any added parameters and before the ? in the URL) on any view of an individual work. The IIIF manifest will provide sequencing information for multiple pages or images or files using the specified IIIF API Presentation context. These will show as a list of canvases and the title of the work will be referred to as the label.

   • JSON views of Works: Another option is to add ".json" at the end of the URL (before any added parameters and before the ? in the URL) on any view of an individual work. Regardless of whether or not the IIIF viewer is being used to show the work, this provides a JSON view of all descriptive metadata for this work as defined for the work type in that instance of Hyrax.

   • Accessibility Settings

9. Previous Version Features

C. For Content Managers (Confluence)

1. Metadata Management Best Practices

2. Bulk Import/Export Using Bulkrax

   1. Bulkrax Round Tripping (Export then Import to make updates)

   2. Hyrax Batch Features

3. Work Type Selection Guidelines

4. Collection Organization Strategies

D. For Repository Contributors (Confluence)

This will be documentation for end users of Hyrax.

1. Content Submission Guides by Work Type

2. Metadata Entry Guidelines

3. File Format Recommendations

4. Proxy Depositors

E. For Developers (GitHub)

1. Installation

   • Environment Setup

   • Production Installation

   • Development Installation

   • Docker Configuration

2. Configuration

   • Initial Configuration

   • Storage Options

   • Authentication Integration

   • Search Configuration

3. Customization

   • Creating Custom Work Types

   • Metadata Customization

   • UI/UX Customization

4. APIs and Integration (not part of Hyrax but should be in future)

   • API Reference

   • External System Integration (Avalon, Archivematica)

   • OAI-PMH Configuration

5. Performance and Scaling

6. Migration Tools and Strategies

7. Contributing to Hyrax

8. Development Patterns Guide

Cross-Cutting Resources (Both Platforms)

[Not sure if this applies to Hyrax, but maybe?]

1. Glossary

2. FAQ by User Segment

3. Troubleshooting Guides

4. Community Resources

5. Version Information

   • Version History

   • Upgrade Guides

   • Feature Preview (v6.2 Flexible Metadata, GA4, Rails 7.x)

A. Overview

The Hyrax documentation has the following goals and constraints:

1. Meet the needs of the readers

2. Enable easy maintenance for contributors

Without clear organization for discoverability and clarity of purpose, both of those goals will be difficult to achieve.

The new proposed structure is very much oriented around the following segments, assuming the following goals of each.

A.1. Hyrax Documentation Reader Segments and Goals

Market Segment

Readers: Library IT management, librarians, archivists, and research data repository managers End Goals:

• Evaluating Hyrax against alternatives for institutional needs

• Understanding total cost of ownership and resource requirements

• Building business cases for implementation

• Aligning repository capabilities with institutional strategic goals

• Planning for migrations from legacy systems

Repository Administrators

Readers: Institutional repository managers, special collections administrators, and library technical staff End Goals:

• Configuring repositories to meet institutional policies

• Managing day-to-day operations efficiently

• Setting up appropriate access controls and workflows

• Customizing the repository appearance and behavior

• Monitoring usage and generating administrative reports

• Ensuring accessibility compliance

Content Managers

Readers: Librarians, archivists, and collection curators responsible for content End Goals:

• Establishing consistent metadata practices

• Efficiently ingesting and managing large collections

• Organizing collections for optimal discoverability

• Managing workflows for content approval and publication

• Implementing appropriate content display strategies

Repository Contributors

Readers: Researchers, faculty, students, and other content creators End Goals:

• Successfully submitting content with minimal friction

• Understanding metadata requirements for different content types

• Selecting appropriate file formats for long-term preservation

• Managing their own deposited content

Developers and Technical Users

Readers: Software engineers, IT staff, and systems administrators End Goals:

• Installing and configuring Hyrax in various environments

• Extending functionality through customization

• Integrating with other institutional systems

• Optimizing performance for specific use cases

• Migrating data between systems

• Contributing improvements back to the community

• Troubleshooting technical issues

Each segment approaches the documentation with distinct technical knowledge levels and primary concerns, requiring tailored content organization and presentation strategies.