Documentation UX analysis and improvement proposals

[Copilot]

Comprehensive analysis of fcli's documentation build process (425 Picocli-generated man pages, Gradle orchestration, Jekyll/static HTML deployment) with concrete improvement proposals addressing command discoverability, navigation, and enterprise requirements.

Deliverables (7 documents, 90KB)

Start here:

• NEW-REQUIREMENTS-SUMMARY.md - Response to additional requirements
• ANALYSIS-SUMMARY.md - Complete overview

Technical specifications:

• docs-improvement-analysis.md - Original 8 proposals with implementation details
• ADDITIONAL-UX-IMPROVEMENTS.md - 15 modern best practices + PDF generation
• VISUAL-OVERVIEW.md - Architecture diagrams and metrics
• ISSUE-documentation-improvements.md - Ready-to-post GitHub issue template
• DOCS-ANALYSIS-README.md - Quick reference

Key Findings

Current state:

• 425 separate HTML files, no search, 30-60s to find commands
• 834-line monolithic index.adoc (2288 lines as HTML)
• 17MB total when browsing all pages

Proposed improvements (23 total):

Phase 1: Foundation (2-3 weeks)

• Combined command reference - Single page with hierarchical TOC
• Client-side search - Lunr.js, fuzzy matching, 200KB index
• Breadcrumb navigation - Visual hierarchy on all pages

Additional High-Priority Items (7-9 days)

• Dark mode - localStorage + CSS custom properties
• Copy-to-clipboard - All code blocks, navigator.clipboard API
• PDF generation ⭐ - AsciidoctorPDF with custom theme
• Command palette - Cmd/Ctrl+K, keyboard-driven navigation
• Version warnings - Alert for deprecated/old version content

Medium/Low Priority

• Related commands, anchor links, edit links, recently viewed
• Progressive disclosure, cheat sheet, syntax highlighting
• Keyboard shortcuts, feedback widget, right TOC, interactive examples

PDF Generation Implementation

Complete AsciidoctorPDF integration:

// New Gradle tasks
val generatePdfSource = tasks.register<Copy>("generatePdfSource") {
    // Combines all 425 .adoc files into master document
}

val generatePdf = tasks.register<AsciidoctorTask>("generatePdf") {
    baseDirFollowsSourceFile()
    outputOptions { backends("pdf") }
    // Custom theme with Fortify branding
}

val distDocsPdf = tasks.register<Copy>("distDocsPdf") {
    // Packages fcli-{version}-documentation.pdf for release assets
}

Output: 5-10MB PDF with TOC, bookmarks, cross-references, syntax highlighting

Expected Impact

• 6x faster command discovery (30-60s → <10s)
• 96% file size reduction for browsing (17MB → 750KB)
• Modern UX (search, dark mode, command palette)
• Enterprise PDF export for offline/air-gapped environments
• 100% backward compatible (individual pages still generated)

Implementation Strategy

Quick wins (7-9 days): Dark mode, copy buttons, PDF, command palette, version warnings
Phase 1 (2-3 weeks): Combined reference, search, breadcrumbs
Complete (8-11 weeks): All 23 improvements

All proposals include implementation code (Gradle, Java, JavaScript, CSS, HTML), effort estimates, and impact assessments.

Original prompt

In the context of this request, fcli build process generates two types of documentation; Jekyll-based HTML pages for deployment to GitHub pages (deployed to gh-pages branch in version-specific directories), and static HTML pages for the current version (deployed as docs-html.zip in release assets). For now, both documentation sets are mostly the same, apart from version selector on gh-pages.

Version-specific docs are generated from AsciiDoc files, both manually maintained or auto-generated, for example through standard picocli functionality for generating man-pages, or fcli build-time actions. All of this is orchestrated through a combination of Gradle build and ci.yml GotHub workflow.

Please analyse current implementation and provide suggestions for improvement, in particular for improving user experience. Please list background info, suggestions, and implementation plan for each suggestion, in a new GitHub issue (if possible, otherwise generate a PR for dev/v3.x branch).

Some ideas raised earlier:

• Combine man-pages into a single document, listing all fcli (runnable) commands in ToC; combine existing pages in Gradle task, or have a custom (Java) implementation for building single doc page?
• Search functionality, either client-side (available for both static HTML and Jekyll), or if it provides befenits/easier implementation, a Jekyll-only approach
• Breadcrumb navigation, including suggestions on how to restructure current docs to provide more user-friendly navigation
• Any other improvements that might improve user experience

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.