/
Proposed Hyku Documentation Structure

Proposed Hyku Documentation Structure

A. Overview

The Hyku 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. Hyku Documentation Reader Segments and Goals

Market Segment

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

End Goals:

  • Evaluating Hyku 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 Hyku 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.

B. Platform Organization

B.1. GitHub Wiki & Repository Docs

  • Technical reference documentation

  • Developer guides

  • Configuration instructions

  • API documentation

  • Installation guides

B.2. Confluence

  • Conceptual & overview documentation

  • End-user tutorials

  • Administrator guides

  • Decision-making resources

  • Community resources

1. Market Segment (Confluence)

1.1 Hyku Overview

Comprehensive explanation of Hyku, its relationship to Hyrax and Samvera, and its primary use cases.

1.2 Features and Capabilities

Detailed breakdown of Hyku features, focusing on institutional benefits and differentiation from alternatives.

1.2.1 Accessibility Compliance

Documentation of Hyku's accessibility features, compliance with standards, and institutional requirements.

1.3 Comparison Guides

1.3.1 Hyku vs. Other Repository Solutions

Comparison with DSpace, Islandora, etc., with feature matrices and use case recommendations.

1.3.2 Persistence Options

Comparison of PostgreSQL vs. Fedora 6 approaches with institutional implications.

1.4 Case Studies

Real-world implementation examples across different types of institutions.

1.5 Implementation Planning

1.5.1 Resource Requirements

Hardware, hosting, and personnel recommendations.

1.5.2 Migration Pathways

Options for migrating from other repository systems.

1.5.3 Total Cost of Ownership

Breakdown of ongoing maintenance costs and considerations.

1.6 Roadmap and Future Development

Upcoming features and community development priorities.

 

2. Current Users

2.1 Repository Administrators (Confluence)

2.1.1 Administrative Dashboard Guide

Complete walkthrough of administrator interfaces and capabilities.

2.1.2 Multi-Tenancy Management

Strategies for setting up and managing multiple tenants with different needs.

2.1.3 User Management

Creating, modifying, and managing user roles and permissions.

2.1.4 Collection Management

Best practices for organizing and displaying collections.

2.1.5 Workflow Configuration

Setting up and managing submission and approval workflows.

2.1.6 Theming and Branding

Guidelines for customizing appearance through admin settings.

2.1.7 Analytics and Reporting

Using and interpreting built-in analytics features.

2.1.8 Content Display Configuration

Comprehensive guide to setting up and configuring content display options.

2.1.8.1 Viewer Technologies

Comparison and configuration of PDF.js vs. Universal Viewer and other viewing options.

2.1.8.2 IIIF Implementation

Setting up and managing IIIF support, manifests, and integration with viewers.

2.1.8.3 Accessibility Settings

Configuration options for ensuring repository accessibility compliance.

2.2 Content Managers (Confluence)

2.2.1 Metadata Management

Best practices for consistent metadata application and management.

2.2.2 Bulk Import/Export

Step-by-step guides for using Bulkrax for various import scenarios.

2.2.3 Work Type Selection Guide

Decision tree for selecting appropriate work types for different materials.

2.2.4 Collection Organization Strategies

Best practices for organizing content to enhance discoverability.

2.3 Repository Contributors (Confluence)

2.3.1 Content Submission Guides

Step-by-step submission tutorials for different work types.

2.3.2 Metadata Entry Guidelines

User-friendly explanation of metadata fields and their importance.

2.3.3 File Format Recommendations

Recommendations for sustainable file formats for different content types.

 

 

3. Developers and Technical Users

3.1 Installation (GitHub)

3.1.1 Environment Setup

Technical requirements and environment configuration.

3.1.2 Production Installation

Step-by-step guide for production deployments.

3.1.3 Development Installation

Local development environment setup instructions.

3.1.4 Docker Configuration

Container-based deployment options and configurations.

3.2 Configuration (GitHub)

3.2.1 Initial Configuration

Post-installation configuration options and recommendations.

3.2.2 Storage Options

Configuring different storage backends (S3, local, etc.).

3.2.3 Authentication Integration

LDAP, Shibboleth, and other authentication system integration.

3.2.4 Search Configuration

Solr configuration and optimization for different use cases.

3.3 Customization (GitHub)

3.3.1 Hyku Knapsack

Guide to using Hyku Knapsack for sustainable customizations.

3.3.2 Creating Custom Work Types

Step-by-step guide with code examples.

3.3.3 Metadata Customization

Technical approach to adding or modifying metadata fields.

3.3.4 UI/UX Customization

Beyond admin-level theming, frontend development guide.

3.4 APIs and Integration (GitHub)

3.4.1 API Reference

Complete API documentation with examples.

3.4.2 External System Integration

Guides for integrating with LMS, discovery layers, etc.

3.4.2.1 Avalon Media Integration

Specific documentation for integrating with Avalon Media System.

3.4.2.2 Archivematica Integration

Guidelines for connecting Hyku with preservation systems.

3.4.3 OAI-PMH Configuration

Detailed setup for metadata harvesting.

3.5 Performance and Scaling (GitHub)

3.5.1 Performance Optimization

Tuning Hyku for different scales of content and users.

3.5.2 Scaling Strategies

Architectural approaches for high-volume repositories.

3.5.3 Monitoring and Maintenance

Technical guides for ongoing system health.

3.6 Migration (GitHub)

3.6.1 Data Migration Tools

Technical documentation for migration adapters and tools.

3.6.2 Validation and Testing

Approaches for validating migrations.

3.6.3 PostgreSQL vs. Fedora Migration

Technical details of migrating between persistence layers.

3.7 Contributing to Hyku (GitHub)

3.7.1 Development Setup

Getting started with Hyku development.

3.7.2 Testing Framework

Using and extending Hyku's test suite.

3.7.3 Pull Request Guidelines

Community standards for contributions.

 

 

4. Cross-Cutting Resources

4.1 Glossary (Both platforms)

Comprehensive glossary of Hyku, Samvera, and digital repository terminology.

4.2 FAQ (Confluence)

Frequently asked questions organized by user segment.

4.3 Troubleshooting Guides (GitHub)

Common issues and their solutions.

4.4 Community Resources (Confluence)

4.4.1 Mailing Lists and Slack

Information on joining community discussions.

4.4.2 Working Groups

Active working groups and their focus areas, including the Accessibility Working Group.

4.4.3 Events and Meetings

Regular community events and how to participate.

4.5 Version Information (Both platforms)

4.5.1 Version History

Detailed changelog and version differences.

4.5.2 Upgrade Guides

Version-specific upgrade instructions.

4.5.3 Feature Preview

Documentation of upcoming features with implementation timelines and guidance.

4.5.3.1 Flexible Metadata (v6.2)

Detailed information about the flexible metadata implementation and migration.

4.5.3.2 Google Analytics 4 Support

Implementation details for GA4 integration.

4.5.3.3 Rails 7.x Upgrade (v7.0)

Preparation guidance for the Rails framework upgrade.