Best Practices

Documentation Organization

Do: ✓ Group related topics together ✓ Use descriptive titles ✓ Keep sections focused and concise ✓ Link related pages ✓ Provide examples

Don’t: ✗ Mix unrelated topics in one page ✗ Use vague titles ✗ Create overly long pages ✗ Leave broken links ✗ Forget to update old documentation.

Writing for Mobile

Maven Skin is responsive. When writing documentation:

  • Use shorter paragraphs
  • Use descriptive headers (helps screen readers)
  • Avoid very wide code lines
  • Use tables sparingly (stack on mobile)
  • Test locally with mvn site and check mobile rendering

Dark Mode Considerations

Content looks good in both themes:

  • Avoid hardcoding colors in images
  • Use high contrast for text
  • Use semantic HTML (provided by AsciiDoc)
  • Test both light and dark modes
  • Don’t rely on color alone to convey information

Example: Instead of "Click the red button", use "Click the Send button".

Performance Optimization

Optimize your site:

  • Keep images reasonably sized (~50-100KB each)
  • Use descriptive image names
  • Organize CSS and JavaScript efficiently
  • Minimize external dependencies
  • Use <placeholder> for large code examples
  • Link to large resources instead of embedding

Versioning

Multiple documentation versions:

If you maintain multiple versions:

<!-- In site.xml -->
<menu name="Documentation">
  <item name="Latest (1.0)" href="/latest"/>
  <item name="1.0" href="/docs/1.0"/>
  <item name="0.9" href="/docs/0.9"/>
</menu>

Or use GitHub branches:

git checkout -b docs-v1.0
# Modify documentation
git push origin docs-v1.0
# Set up separate GitHub Pages for this branch

Maintenance

Keeping Documentation Current

Set a schedule:

  • Review documentation quarterly
  • Update examples with new versions
  • Fix broken links regularly
  • Archive old documentation
  • Encourage community contributions

Content Update Workflow

# 1. Edit documentation
edit src/site/asciidoc/my-page.adoc

# 2. Test locally
mvn clean site
open target/site/index.html

# 3. Commit changes
git add src/site/
git commit -m "Update documentation: added new section"

# 4. Push to trigger deployment
git push origin main

# 5. Verify on GitHub Pages
# Visit: https://your-domain.com

Tips & Tricks

Automatic TOC

Add to top of your document:

:toc:
:toclevels: 3

Code Block Callouts

[source,java]

public class Hello { System.out.println("Hello"); // <1> }

<1> This line prints the greeting

Attributes

:project-name: My Project
:version: 1.0.0

== {project-name} v{version}

Welcome to {project-name}!

Include External Files

include::../code-examples/HelloWorld.java[]

This helps keep documentation and code examples in sync.

Next Steps

  1. Create your first documentation page
  2. Set up local site generation: mvn clean site
  3. Review the generated site in target/site/
  4. Deploy to GitHub Pages with the workflow
  5. Iterate and improve based on user feedback

Happy documenting! 📚