SPIKE: Migrate Documentation Structure, Add Output Format Options, and Define Future Enhancements

[miroslavpojer]

Background

The current documentation in AbsaOSS/living-doc-generator-mdoc needs to be migrated and reorganized to follow the documentation structure used by @AbsaOSS/generate-release-notes.

This spike will:

• Review the current repo documentation set and structure.
• Propose how to update documentation to include complete, accurate information about the project.
• Explicitly focus on report-page and define its role in the tool.
• Introduce an input to define output format (currently supported value: mdoc) and update docs accordingly.
• Add support for a new output format: markdown (this becomes the new default), and plan the rename of the repository to living-doc-generator-markdown.
• Based on the above analysis, propose one additional future improvement within the scope of automated living documentation for this tool.

Expected output of this spike’s implementation work:

• Create 1+ specification files under {root}/docs/spec/
• Create TASKS.md in the repository root

Questions To Answer

1. What documentation files and structure exist today in living-doc-generator-mdoc, and how do they differ from the structure in generate-release-notes?
2. What is the intended role of report-page (inputs, outputs, generated artifacts, relationship to other features), and what should the documentation say about it?
3. What is the required input contract for selecting output format (including current mdoc behavior), and which docs must be updated to reflect it?
4. What does “markdown output” mean for this project (generated files structure, naming, feature pages, report pages), and how does it relate to other inputs—especially structured-output?
5. What steps are required to make markdown the default output format, and what are the impacts/steps for renaming to living-doc-generator-markdown (docs, action name/usage, examples, compatibility notes)?
6. After analyzing goals 1–3 and the code/doc structure, what is one additional scoped future improvement that stays within living documentation and this tool’s purpose?

Desired Outcome

• A documented plan to migrate docs and doc structure to match @AbsaOSS/generate-release-notes, including a mapping from old docs to new locations/structure.
• Updated and complete documentation content describing the project, with a clear definition and explanation of report-page.
• A clear specification for an output-format input (or equivalent), explicitly documenting supported values (at minimum: mdoc, markdown) and defaults.
• A full specification for markdown output (as the new default), including:
  • expected generated artifacts and folder/file structure
  • relationship to structured-output
  • compatibility/upgrade notes from mdoc
• A rename plan to living-doc-generator-markdown (documentation changes, references, examples, and rollout considerations).
• One additional future improvement proposal (within scope), with rationale and a high-level plan.

Tasks

• Questions have been answered or we have a clearer idea of how to get to our goal
• Discussion with the team
• Documentation
• Create recommendations and new implementation tickets

Additional Info/Resources

1. Reference structure and documentation approach: https://github.com/AbsaOSS/generate-release-notes
2. Spike deliverables expected from implementation:
   • {root}/spec/ contains 1+ spec files
   • {root}/TASKS.md exists and breaks down implementation tasks into actionable items