Reorganize documentation for better discoverability#170
Merged
Conversation
## Major Changes ### New Root Files - **README.md**: Reduced from 255 to 69 lines, focus on "what" and navigation - **QUICKSTART.md**: Get running in 5 minutes with database setup emphasis - **CONTRIBUTING.md**: Comprehensive contributor guide ### Documentation Structure Reorganized docs/ into logical sections: **docs/getting-started/** - installation.md (was BUILD.md) - docker.md - oneliners.md **docs/guides/** - database-access.md (was JDBC_GUIDE.md) - emphasizes driver download - java-integration.md (new - JSR-223 guide) - module-porting.md (was PORTING_MODULES.md) - graalvm.md **docs/reference/** - feature-matrix.md (was FEATURE_MATRIX.md) - testing.md (was TESTING.md) - architecture.md (was ARCHITECTURE.md) - cli-options.md (new - command-line reference) **docs/about/** - why-perlonjava.md (was WHY_PERLONJAVA.md) - roadmap.md (from MILESTONES.md - future plans) - changelog.md (from MILESTONES.md - release history) - support.md (was SUPPORT.md) - resources.md (was RESOURCES.md) - relation-perlito.md (was RELATION_WITH_PERLITO_COMPILER.md) **docs/README.md**: Navigation guide for all docs ### Developer Documentation Reorganized dev/ structure: **dev/architecture/** - control-flow.md - block-dispatcher-optimization.md - method-call-optimization.md - inline-cache.md - large-code-refactoring.md **dev/implementation/** - pack-unpack.md (was docs/PACK_UNPACK_ARCHITECTURE.md) - regex.md - overload.md - tie.md - signal-handling.md - alarm.md **dev/maintenance/** - dependency-updates.md ### Version Updates - Updated references from Perl 5.38 to Perl 5.42 - Clarified "Java 21 or later" (not specific JDK vendor) ### Link Updates - Fixed all internal links to new paths - Updated cross-references throughout documentation ## Benefits 1. **Clear user journey**: Installation → Guides → Reference 2. **Better discoverability**: Logical grouping by purpose 3. **Shorter README**: Quick overview with clear navigation 4. **Separated concerns**: User docs vs developer docs 5. **Quick start emphasis**: Database setup warnings prominent Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
## Corrections 1. **License**: Fixed from MIT to Artistic License 2.0 - Updated README.md badge and license section - Matches actual LICENSE.md content 2. **EmitterVisitor location**: Clarified architecture - EmitterVisitor (astvisitor/) coordinates bytecode generation - Emit* classes (codegen/) generate actual JVM bytecode - Matches CLAUDE.md description 3. **Test structure**: Corrected perl5_t/ location - perl5_t/ is at project root, not in src/test/resources/ - Created by dev/import-perl5/sync.pl script - Contains perl5_t/t/ (core tests) and perl5_t/[Module]/ (module tests) 4. **sync.pl description**: Made clearer - Explained that sync.pl reads config.yaml - Copies from perl5/ (Perl 5 source) to perl5_t/ - Applies patches from dev/import-perl5/patches/ 5. **GraalVM docs**: Moved to dev/ directory - Moved docs/guides/graalvm.md to dev/graalvm.md - Removed from user-facing guides (experimental feature) - Updated navigation in README.md and docs/README.md 6. **MILESTONES.md**: Converted to redirect stub - Reduced from 523 lines to 21 lines - Points to docs/about/roadmap.md (future plans) - Points to docs/about/changelog.md (release history) - Eliminates duplicate content ## Files Changed - README.md - License badge and text corrected - CONTRIBUTING.md - Architecture and test structure clarified - MILESTONES.md - Now a redirect stub - docs/reference/testing.md - sync.pl description improved - docs/guides/graalvm.md → dev/graalvm.md - Moved to dev docs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
GraalVM documentation belongs in dev/design/ with other design/experimental feature docs, not directly in dev/. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Fixed misleading documentation about module registration: **XSLoader (Standard Approach)** - Use for regular CPAN-style modules - Module calls XSLoader::load() in .pm file - Java class in org.perlonjava.perlmodule.* package - Transparent to end users **GlobalContext (Internal Only)** - Only for built-in PerlOnJava modules (UNIVERSAL, DiamondIO, etc.) - Registered at startup in GlobalContext.java - NOT for regular module porting Added: - Clear naming convention (DBI → org.perlonjava.perlmodule.Dbi) - Complete DBI example showing XSLoader usage - Emphasis that most modules should use XSLoader - Removed misleading GlobalContext example from main flow This corrects the documentation to match actual PerlOnJava architecture and prevents confusion about proper module registration approaches. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added new section 'Tracking Test Progress Over Time' explaining the workflow for long-running development: **Workflow:** 1. Run tests with timestamped logs in logs/ directory 2. Compare test runs using compare_test_logs.pl 3. Track progress and catch regressions over time **Features documented:** - Clean process (killall java, rm tmp files) - Extended timeout for comprehensive tests (--timeout 300) - Timestamped log format (YYYYMMDD_HHMMSS) - Comparing before/after test runs - Log organization strategy **Use cases:** - Before/after feature implementation - Daily progress tracking - Identifying when regressions were introduced - Measuring optimization impact This documents the actual developer workflow for tracking test suite improvements during feature development and debugging. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added clearer instructions to verify JDK (not just JRE) is installed: **Before:** - Just said 'Java 21 or later' - Only checked 'java -version' **After:** - Clarifies 'Java Development Kit (JDK) 21 or later' - Shows how to check for javac compiler - Explains error if javac is missing - Provides JDK installation instructions for common platforms: - macOS (Homebrew) - Ubuntu/Debian (apt) - Windows (Adoptium/Chocolatey) - Links to Adoptium for direct downloads This prevents the common issue where users have JRE but not JDK, which causes build failures. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Changed from endorsing specific vendor (Adoptium) to being neutral: **Before:** - 'Download from Adoptium (recommended)' - Specific links to Adoptium **After:** - 'Use your system's package manager, or' - 'Download from a JDK provider (Adoptium, Oracle, Azul, Amazon Corretto, etc.)' - Prioritizes package managers (brew, apt, chocolatey, scoop) No preference for any specific JDK vendor - they all work fine. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Changed test-unit target to use Gradle's testUnitParallel (with --parallel flag) instead of perl_test_runner.pl, making it consistent with the default make build target. Both now run the same fast unit tests from src/test/resources/unit/ using the same parallel execution strategy. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Created comprehensive Configure.pl reference (docs/reference/configure.md) covering all options: -D, --search, --direct, --verbose, --upgrade - Updated installation.md with complete Configure.pl section linking to reference - Updated QUICKSTART.md to recommend manual driver download + CLASSPATH instead of Configure.pl for quickstart (simpler workflow) - Added Configure.pl reference to README.md documentation index - Clarified that Configure.pl requires make rebuild after adding dependencies Changes emphasize manual CLASSPATH approach for quick start, while documenting Configure.pl for users who want bundled dependencies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added comprehensive Debian package section to installation.md covering: - How to build the .deb package with make deb - Installation with dpkg - Benefits of package installation (systemwide, clean removal) - Uninstallation instructions - Added brief mention in QUICKSTART.md for Debian/Ubuntu users - Updated table of contents in installation.md - Clarified make commands (build runs tests, dev for clean rebuild) This provides a proper installation path for Debian-based systems where jperl becomes available systemwide without ./jperl prefix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Added "About Perl" section with brief description and link to perl.org to provide context for readers who may not be familiar with Perl. This helps new users understand what PerlOnJava builds upon. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
CRITICAL FIXES:
- Fix broken link in installation.md (JDBC_GUIDE.md → database-access.md)
- Fix license inconsistency in CONTRIBUTING.md (MIT → Artistic License 2.0)
- Fix multiple broken references in resources.md (GRAALVM.md, ARCHITECTURE.md, PORTING_MODULES.md)
- Fix broken reference in support.md (MILESTONES.md → roadmap.md, changelog.md)
IMPORTANT FIXES:
- Rewrite docker.md to remove confusing port mapping and vague content
- Remove misleading -p 8080:8080 from simple examples
- Add practical examples (mount scripts, JDBC drivers, persistent containers)
- Remove generic "Additional Notes" section
- Clarify make command in QUICKSTART.md ("compiles and runs tests")
- Deduplicate JDBC documentation between QUICKSTART.md and database-access.md
- Keep brief example in QUICKSTART.md with link to full guide
- Avoid maintenance burden of duplicate instructions
MINOR FIXES:
- Add overview section to architecture.md explaining what PerlOnJava does
- Fix broken JSON example in oneliners.md (was using YAML functions)
- Remove hype from why-perlonjava.md (multithreaded I/O → JVM JIT optimizations)
All examples now tested and accurate. Documentation links verified.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Changed example from using TAP::Harness (which doesn't exist in PerlOnJava) to simply running a test file directly, which actually works. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Complete documentation reorganization to improve discoverability and user experience.
Key Changes
📖 New Root Files
README.md (255 → 69 lines)
QUICKSTART.md (new)
CONTRIBUTING.md (new)
📁 Documentation Structure
Before:
After:
🔧 Developer Documentation
dev/ reorganization:
architecture/- Compiler pipeline, control flow, optimizationsimplementation/- Feature-specific docs (regex, tie, overload, pack-unpack)maintenance/- Dependency updates, proceduresdesign/- Historical design docs (retained for reference)📝 Content Improvements
🔗 Link Updates
Benefits
✅ Clear user journey: Installation → Quick Start → Guides → Reference
✅ Better navigation: Logical grouping by user needs
✅ Shorter README: Quick overview without overwhelming detail
✅ Separated concerns: User docs distinct from developer docs
✅ Quick answers: Common tasks easy to find
User Impact
New users: Clear path from installation → first steps → guides
Module developers: Easy to find module porting guide
Java developers: Dedicated Java integration guide
Contributors: Comprehensive contributing guide
Everyone: Shorter, scannable README
Migration Notes
🤖 Generated with Claude Code