mirror of
https://github.com/JuliaFEM/JuliaFEM.jl.git
synced 2026-09-16 16:53:19 +00:00
Jukka Aho
626266c990
**Three Manuals for Three Audiences:** 1. **User Manual** (docs/user/) - "Just Get It Done" - For end users, engineers, students - Simple, practical, step-by-step - Quick start, tutorials, examples, troubleshooting - Philosophy: Show me how to solve my problem 2. **Contributor Manual** (docs/contributor/) - "Show Me the Code" - For developers, contributors, advanced users - Technical, detailed, design rationale - Testing, architecture, performance, CI/CD - Philosophy: Explain HOW and WHY 3. **The JuliaFEM Book** (docs/book/) - "Let Me Show You How I Think" - For researchers, theory nerds, and Jukka - Comprehensive, educational, opinionated, personal - Math foundations, design philosophy, history, research - Philosophy: Mix theory, code, and personal experience **Reorganization:** - Moved: TESTING_PHILOSOPHY.md → contributor/testing_philosophy.md - Moved: STATUS.md → contributor/status.md - Moved: TEST_FIXES_NEEDED.md → contributor/test_fixes_needed.md - Moved: lagrange_basis_functions.md → book/lagrange_basis_functions.md - Moved: benchmarks/ → book/benchmarks/ - Created: docs/README.md (main index explaining structure) - Created: README.md in each section explaining audience and contents - Updated: All references in scripts and source files **Naming:** All docs now lowercase (testing_philosophy not TESTING_PHILOSOPHY) **Benefits:** - Clear separation of concerns - Users don't get overwhelmed with implementation details - Contributors get technical depth - Book preserves deep theory and personal insights - Each manual optimized for its audience **Next:** Populate each section with appropriate content
119 lines
3.6 KiB
Markdown
119 lines
3.6 KiB
Markdown
# JuliaFEM Documentation
|
|
|
|
Welcome! JuliaFEM documentation is organized into **three manuals** for three different audiences:
|
|
|
|
---
|
|
|
|
## 📘 [User Manual](user/) - "Just Get It Done"
|
|
|
|
**For:** End users, engineers, students who want to run simulations.
|
|
|
|
**Style:** Simple, practical, step-by-step.
|
|
|
|
**Contents:**
|
|
- Quick start and installation
|
|
- Tutorials and examples
|
|
- API reference
|
|
- Troubleshooting
|
|
|
|
**Philosophy:** Show me how to solve my problem, skip the lectures.
|
|
|
|
👉 **[Start Here](user/README.md)** if you want to run simulations.
|
|
|
|
---
|
|
|
|
## 🔧 [Contributor Manual](contributor/) - "Show Me the Code"
|
|
|
|
**For:** Developers, contributors, advanced users who want to extend JuliaFEM.
|
|
|
|
**Style:** Technical, detailed, design rationale.
|
|
|
|
**Contents:**
|
|
- Testing philosophy
|
|
- Code style and architecture
|
|
- Performance guidelines
|
|
- How to add elements
|
|
- CI/CD and git workflow
|
|
|
|
**Philosophy:** Explain HOW the code works and WHY we made these choices.
|
|
|
|
👉 **[Start Here](contributor/README.md)** if you want to contribute code.
|
|
|
|
---
|
|
|
|
## 📖 [The JuliaFEM Book](book/) - "Let Me Show You How I Think"
|
|
|
|
**For:** Advanced researchers, theory nerds, those who want to understand deeply. And Jukka.
|
|
|
|
**Style:** Comprehensive, educational, opinionated, personal.
|
|
|
|
**Contents:**
|
|
- Mathematical foundations (Lagrange basis, contact mechanics, etc.)
|
|
- Design philosophy and technical vision
|
|
- Strategic mistakes and lessons learned (2015-2019)
|
|
- Research directions (nodal assembly, matrix-free, etc.)
|
|
- Personal reflections on the journey
|
|
|
|
**Philosophy:** Mix theory, software design, and personal experience. Teach FEM through implementation.
|
|
|
|
👉 **[Start Here](book/README.md)** if you love deep dives and want to understand the "why" behind everything.
|
|
|
|
---
|
|
|
|
## Quick Navigation
|
|
|
|
### I want to...
|
|
|
|
- **Solve a heat transfer problem** → [User Manual](user/)
|
|
- **Add a new element type** → [Contributor Manual](contributor/)
|
|
- **Understand Lagrange basis functions** → [Book: Lagrange Basis](book/lagrange_basis_functions.md)
|
|
- **Learn about testing** → [Contributor: Testing Philosophy](contributor/testing_philosophy.md)
|
|
- **See benchmark results** → [Book: Benchmarks](book/benchmarks/)
|
|
- **Understand the design philosophy** → [Book: Philosophy](book/)
|
|
- **Report a bug** → GitHub Issues
|
|
- **Ask a question** → GitHub Discussions
|
|
|
|
---
|
|
|
|
## Documentation Philosophy
|
|
|
|
### Why Three Manuals?
|
|
|
|
Different readers have different needs:
|
|
|
|
1. **Users** don't care about implementation details - they just want working code.
|
|
2. **Contributors** need technical depth but not necessarily all the theory.
|
|
3. **Researchers** (and Jukka) want to understand everything from first principles.
|
|
|
|
Mixing these audiences in one manual makes it too complex for users and too shallow for researchers.
|
|
|
|
### Design Principles
|
|
|
|
- **User Manual:** Optimize for time-to-first-result
|
|
- **Contributor Manual:** Optimize for correctness and maintainability
|
|
- **Book:** Optimize for understanding and education
|
|
|
|
### Cross-References
|
|
|
|
Manuals link to each other when appropriate:
|
|
- User manual links to theory when deeper understanding helps
|
|
- Contributor manual links to book for design rationale
|
|
- Book links to code examples and practical guides
|
|
|
|
---
|
|
|
|
## Contributing to Documentation
|
|
|
|
Documentation improvements are always welcome!
|
|
|
|
- **User docs:** Fix errors, add examples, improve clarity
|
|
- **Contributor docs:** Update for new features, clarify architecture
|
|
- **Book:** Add theory, share insights, document research
|
|
|
|
See [Contributor Manual](contributor/) for guidelines.
|
|
|
|
---
|
|
|
|
**License:** MIT (same as code)
|
|
**Questions?** Open an issue or discussion on GitHub
|