Outline Antora's end user documentation structure
We've created enough files in the Antora docs that now is a good time to sort them into a cohesive user flow, identify gaps, and refine names to map to users' mental models.
Items that we need to sort, name, decide on and/or explore further include (but by no means are limited to):
- What is Antora (big picture/intro)
- Who is it for/What problems does it solve
- Requirements/skills for content, system, user, software
- Installation per user type/environment/usecase
- Inputs/project/repo/folder structure
- Content
- Asset storage and management
- Configuration (as code for playbook, environment setups)
- Code snippets and sample projects storage and management
- Content
- Pages
- Partials
- Topics
- Modules/Collections/Groups/Sections
- Versioning
- Page structure
- Header/frontmatter
- titles
- page ID
- page aliases
- keywords
- attributes
- metadata/special processing instructions
- Preamble/Abstract
- Sections
- Source blocks
- Example blocks
- Admonition blocks
- Images/Media
- Cross references/internal links/deep links
- External links
- Macros
- AsciiDoc syntax
- Playbook
- Set up
- Usage
- UI
- Add theme
- Templates
- Search
- Navigation templates/config
- Navigation
- Set up
- Patterns
- Validations
- Run/Operate/Publish
- Local
- Testing/Dev/Staging
- Production
- Multi-site/Multi-ui
- Antora
- Lifecycle
- Standard pipeline
- Adding/removing pipeline packages
- Updating/upgrading
- Custom packages
- API
- Migration
- Syntax
- IA/storage structure
- Testing/Dev/Staging environment
- Production environment
- CI/CD workflow
Regarding terminology and common mental models, as Dan said:
We need to give some more thought to the best way to organize this information. Maybe we're grouping explanation and reference at bit too much. We might consider studying the documentation for grav, hugo, jekyll, and middleman to see what strikes as logical, then try to apply what we like to our own structure.
We should conduct a brief "literature review" to identify terms/flows that resonate with users/confuse them and make sure we align with the positive and avoid areas of friction.