GitHub user ryankert01 created a discussion: RFC: Modernizing Project Documentation with Docusaurus and Automated Sync Workflow
### **Context** Following our recent community call, we discussed the need to modernize our documentation infrastructure. The goal is to make it easier for contributors to write documentation while maintaining a high-quality, searchable website. Based on our conversation, I’m proposing we adopt **Docusaurus** and implement a specific documentation sync workflow. ### **The Proposal: Docusaurus** I propose we move our website/documentation framework to **Docusaurus**. * **Why:** It is a React-based static site generator that handles Markdown-to-HTML beautifully. It is developer-friendly, provides excellent SEO, and supports versioning. * **Ease of Use:** As discussed, it allows us to focus on content in Markdown without needing to manage complex HTML/CSS layouts manually. ### **Documentation Workflow: The "Sync" Approach** To keep the repository clean and contributor-friendly, I'd like to recreate a workflow previously used in the `gofannon` project: 1. **Source of Truth:** All documentation will live in a top-level `/docs` directory in the main branch. 2. **Build Process:** During the site build, a script will copy the contents of `/docs` into the `/website` directory. 3. **Reference:** We can adapt the sync script used here: [[sync_docs.py (gofannon)](https://github.com/The-AI-Alliance/gofannon/blob/2eaf7d22a80f4ed8794c02b074ccda137b51ea0b/website/scripts/sync_docs.py)](https://github.com/The-AI-Alliance/gofannon/blob/2eaf7d22a80f4ed8794c02b074ccda137b51ea0b/website/scripts/sync_docs.py). ### **Architectural Decision Record (ADR)** In the spirit of preserving project history and the "why" behind our technical choices, I also propose we can update our design with an **ADR**. This ensures that future maintainers understand our reasoning for choosing Docusaurus and this specific sync logic, preventing the "deep-magic" knowledge gaps that can occur during transitions. ### **Seeking Community Feedback** I’m opening this discussion to the community for feedback: * Are there any concerns with using a React-based framework like Docusaurus? * Does anyone have alternative suggestions for the sync workflow? * If there is general consensus (or "lazy consensus"), I am happy to lead the initial setup and migration. I look forward to hearing your thoughts! GitHub link: https://github.com/apache/mahout/discussions/882 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected]
