Add a catching GIF to explain FDS in readme

[jy95]

Many projects use a catching gif to fastly explain their projects :

• https://github.com/continuedev/continue
• https://github.com/FoxxMD/multi-scrobbler
• ...

Would be nice if this project has it

[jy95]

@coderabbitai plan

[coderabbitai]

Coding Plan

Approach

Ticket Summary

Add an engaging animated GIF to the README that quickly demonstrates how the FDS library converts FHIR Dosage data structures into human-readable text across multiple languages.

Codebase Summary

FHIR Dosage Support (FDS) is a Java library that converts FHIR (Fast Healthcare Interoperability Resources) Dosage structures into human-readable, multilingual text. The project has a multi-module Maven structure with separate modules for FHIR R4 and R5 standards (fhir-dosage-support-r4 and fhir-dosage-support-r5), plus a common module. The main entry points are DosageAPIR4 and DosageAPIR5 classes. The README.md currently contains badges, a logo, and text descriptions but lacks any visual demonstration of the library's core functionality. The project supports multiple languages including English, French, Dutch, and German, and has extensive test cases showing typical usage patterns.

Observations

FHIR Dosage Support (FDS) is a Java library that converts FHIR (Fast Healthcare Interoperability Resources) Dosage structures into human-readable, multilingual text. The project has a multi-module Maven structure with separate modules for FHIR R4 and R5 standards (fhir-dosage-support-r4 and fhir-dosage-support-r5), plus a common module. The main entry points are DosageAPIR4 and DosageAPIR5 classes. The README.md currently contains badges, a logo, and text descriptions but lacks any visual demonstration of the library's core functionality. The project supports multiple languages including English, French, Dutch, and German, and has extensive test cases showing typical usage patterns.

Assumptions

Assumption 1: What type of demonstration should the GIF showcase?

Options Considered:

• A GUI/web demo application showing interactive transformations
• A terminal-based code demo showing actual Java code execution
• A presentation-style animated diagram of the data flow
• An IDE recording showing code being written and executed

Chosen Option: Terminal-based code demo showing a simple Java example being compiled and executed with multilingual output

Rationale: This approach aligns with developer expectations for a Java library, is authentic and reproducible, demonstrates the key features (FHIR input → readable output in multiple languages), and can be created using standard terminal recording tools. Animated GIFs in README files can quickly show core functionality without requiring full video, and users can immediately see how the project works without reading the entire README or downloading the project.

Assumption 2: Where should the GIF file be stored?

Options Considered:

• Store directly in the repository in a dedicated assets/demo directory
• Store in existing src/site/resources/images directory
• Use GitHub's upload mechanism (drag-and-drop into README editor)
• Host externally on platforms like Imgur or Giphy

Chosen Option: Store directly in repository in a docs/demo or .github/images directory

Rationale: Storing the GIF in the repository ensures it's version-controlled, always accessible, and can be updated in the same commit when features change. While adding GIFs as regular files increases repository size, a single optimized GIF (<5MB) is acceptable for demonstrating core functionality. The alternative of dragging GIFs into README uploads to GitHub's servers reduces repo size but creates external dependencies.

Assumption 3: What content should be shown in the GIF?

Options Considered:

• Show only the output transformation (FHIR JSON → readable text)
• Show complete code example with compilation and execution
• Show multiple examples with different dosage types
• Focus on multilingual output as the key differentiator

Chosen Option: Show a simple Java code example that demonstrates conversion in 2-3 languages

Rationale: The GIF should be concise (10-15 seconds) showing: (1) A simple Java code snippet visible on screen, (2) Execution of the code, (3) Output in English, then French or German to highlight internationalization. This showcases both core functionality and the key differentiator (i18n support) without overwhelming viewers.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create Demo Content

Prepare a simple, focused demonstration that showcases FDS's core value proposition: converting FHIR Dosage to readable text in multiple languages.

Task 1: Create Demo Java Application

Develop a minimal standalone Java demo application that demonstrates the library's functionality.

• Create a new directory demo/ at the repository root to hold demo materials
• Write a simple DosageDemo.java file that instantiates DosageAPIR4 with two different locale configurations (e.g., English and French)
• Include a sample FHIR Dosage object creation (can use test data from existing test cases like AsHumanReadableTextTest)
• Show the conversion output for both languages with clear labels (e.g., "English: ...", "French: ...")
• Keep the demo code minimal (20-30 lines) and readable when displayed in terminal
• Add a pom.xml or simple build script for the demo if needed to compile and run standalone

Task 2: Prepare Recording Environment

Set up the terminal environment for clean, professional recording.

• Configure terminal with readable font size (14-16pt) and color scheme with good contrast
• Set terminal dimensions to reasonable size for GIF (recommend 800-1000px width)
• Prepare the demo directory with necessary build artifacts so execution is smooth
• Test run the demo multiple times to ensure consistent timing and output
• Keep any command prompts or outputs concise to fit in GIF frame limits

🤖 Prompt for AI agents

This phase creates demo content to showcase FDS converting FHIR Dosage to
multilingual readable text.

Create Demo Java Application:
- Create `demo/` directory at repository root
- Write `DosageDemo.java` that instantiates DosageAPIR4 with English and French
locales
- Use sample FHIR Dosage object from existing test cases (e.g.,
`AsHumanReadableTextTest`)
- Output conversion results for both languages with clear labels
- Keep code minimal (20-30 lines) and terminal-readable
- Add build configuration (pom.xml or script) for standalone execution

Prepare Recording Environment:
- Configure terminal: readable font (14-16pt), high-contrast colors, 800-1000px
width
- Ensure demo runs smoothly with consistent output
- Keep commands and output concise for GIF display

Phase 2: Record and Process the GIF

Capture the demonstration and optimize the resulting GIF for README usage.

Task 1: Record Terminal Session

Create the animated recording of the demonstration using terminal recording tools.

• Use terminal recording tools like Terminalizer to record the session, or alternatives like Peek for Linux, ScreenToGif for Windows, or Gifox for Mac
• Record a sequence showing: (1) Display the demo code briefly (2-3 seconds), (2) Execute the demo, (3) Show output in first language, (4) Show output in second language
• Keep total recording duration between 10-15 seconds for optimal README viewing
• Reduce frame rate to around 10 frames per second since high frame rates aren't necessary for code demonstrations
• Ensure the recording captures the key message: FHIR data transforms into readable, localized text

Task 2: Optimize GIF File Size

Process the recording to create an optimized GIF suitable for GitHub README.

• Keep the GIF under GitHub's 10MB size limit for uploads
• Use tools like ImageMagick to reduce color palette if needed (e.g., 128-200 colors instead of 256)
• Consider using online compression tools like XConvert or gifski for high-quality compression
• Target final file size of 2-5MB for reasonable load times
• Verify the GIF loops smoothly and animation is clear at various screen sizes
• Save the optimized GIF as demo.gif or fds-demo.gif in the demo directory

🤖 Prompt for AI agents

This phase records the demo and creates an optimized GIF for the README.

Record Terminal Session:
- Use terminal recording tool (Terminalizer, Peek, ScreenToGif, or Gifox)
- Record sequence: display code (2-3 sec) → execute demo → show English output →
show French output
- Keep duration 10-15 seconds total
- Use ~10 fps frame rate
- Ensure the key message is clear: FHIR → readable multilingual text

Optimize GIF:
- Compress to under 10MB (GitHub limit), target 2-5MB
- Use ImageMagick or compression tools (XConvert, gifski) to reduce colors
(128-200 palette)
- Verify smooth looping and clarity at different sizes
- Save as `demo.gif` or `fds-demo.gif` in demo directory

Phase 3: Integrate GIF into README

Add the demonstration GIF to the README in a prominent, contextually appropriate location.

Task 1: Update README with GIF

Modify README.md to include the demonstration GIF with proper positioning and formatting.

• Add a "## Demo" or "## Quick Demo" section in README.md, positioned after the feature highlights but before detailed documentation links
• Use standard Markdown syntax to embed the GIF from the repository: ![FDS Demo](docs/demo/fds-demo.gif) or use relative path if stored elsewhere
• Add descriptive alt text for accessibility (e.g., "Demonstration of FDS converting FHIR Dosage to readable text in multiple languages")
• Optionally add a brief caption below the GIF (1-2 sentences) explaining what viewers are seeing
• Consider image sizing with HTML if needed: <img src="docs/demo/fds-demo.gif" width="600" alt="FDS Demo" />

Task 2: Store GIF in Repository

Add the GIF file to version control in an appropriate location.

• Create a docs/demo/ directory (or alternative like .github/images/) to organize demo assets
• Add the optimized fds-demo.gif file to this directory
• Update .gitattributes if needed to mark the GIF file as binary: *.gif binary
• Include the demo source code (DosageDemo.java and any build files) in demo/ directory for reproducibility
• Add a README in the demo directory explaining how to regenerate the GIF if library functionality changes
• Commit all files with a descriptive message like "Add animated GIF demo to showcase FDS functionality"

🤖 Prompt for AI agents

This phase integrates the demo GIF into the README and commits all assets.

Update README:
- Add "## Demo" or "## Quick Demo" section after feature highlights, before
documentation links
- Embed GIF using Markdown: `![FDS Demo](docs/demo/fds-demo.gif)`
- Include descriptive alt text for accessibility
- Add optional 1-2 sentence caption explaining the demo
- Consider HTML img tag with width="600" if sizing needed

Store GIF in Repository:
- Create `docs/demo/` directory for demo assets
- Add optimized `fds-demo.gif` to this directory
- Update `.gitattributes`: `*.gif binary`
- Include `DosageDemo.java` and build files in `demo/` directory
- Add README in demo directory with regeneration instructions
- Commit with message: "Add animated GIF demo to showcase FDS functionality"

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase creates demo content to showcase FDS converting FHIR Dosage to
multilingual readable text.

Create Demo Java Application:
- Create `demo/` directory at repository root
- Write `DosageDemo.java` that instantiates DosageAPIR4 with English and French
locales
- Use sample FHIR Dosage object from existing test cases (e.g.,
`AsHumanReadableTextTest`)
- Output conversion results for both languages with clear labels
- Keep code minimal (20-30 lines) and terminal-readable
- Add build configuration (pom.xml or script) for standalone execution

Prepare Recording Environment:
- Configure terminal: readable font (14-16pt), high-contrast colors, 800-1000px
width
- Ensure demo runs smoothly with consistent output
- Keep commands and output concise for GIF display
===============================================================================

Task: 2

This phase records the demo and creates an optimized GIF for the README.

Record Terminal Session:
- Use terminal recording tool (Terminalizer, Peek, ScreenToGif, or Gifox)
- Record sequence: display code (2-3 sec) → execute demo → show English output →
show French output
- Keep duration 10-15 seconds total
- Use ~10 fps frame rate
- Ensure the key message is clear: FHIR → readable multilingual text

Optimize GIF:
- Compress to under 10MB (GitHub limit), target 2-5MB
- Use ImageMagick or compression tools (XConvert, gifski) to reduce colors
(128-200 palette)
- Verify smooth looping and clarity at different sizes
- Save as `demo.gif` or `fds-demo.gif` in demo directory
===============================================================================

Task: 3

This phase integrates the demo GIF into the README and commits all assets.

Update README:
- Add "## Demo" or "## Quick Demo" section after feature highlights, before
documentation links
- Embed GIF using Markdown: `![FDS Demo](docs/demo/fds-demo.gif)`
- Include descriptive alt text for accessibility
- Add optional 1-2 sentence caption explaining the demo
- Consider HTML img tag with width="600" if sizing needed

Store GIF in Repository:
- Create `docs/demo/` directory for demo assets
- Add optimized `fds-demo.gif` to this directory
- Update `.gitattributes`: `*.gif binary`
- Include `DosageDemo.java` and build files in `demo/` directory
- Add README in demo directory with regeneration instructions
- Commit with message: "Add animated GIF demo to showcase FDS functionality"

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord or schedule a call!