Topic
The Magnolia documentation contains several kind of examples in different form. This unconference discussion was aimed to get feedback from Magnolia developers / implementers what form of examples they would like to see in terms of:
- Effective learning
- Convenience
Example
Different ways to configure a content app:
| 1) Configure by hand | 2) Download configuration as XML | 3) Clone the complete module | |
|---|---|---|---|
| Effective learning |  | |  |
| Convenience | |  | |
| Pros | Helps you understand components | Fast | |
| Cons | Error-prone Time consuming | Don't learn anything |
Is there a good way between the plain docu which offers some config-tree-fragments which the user must copy/paste and the complete module available from git or jira?
Feedback
Here's what the people joining the session said:
- Tutorials with step-by-step instructions are very welcome.
- Conclusion: We can't just provide a Git link. It is is too simplistic and you don't learn anything. Steps that explain the "what and why" help you understand.
- Writing configuration manually is frustrating and error prone.
- This means XML downloads and Git clones are appreciated.
- Conclusion: An ideal tutorial is a compromise that includes a fast-track option (Git) but also explains the details.
- Idea: Downloadable XML could have gaps, such as asking the reader to fill in missing property values as an exercise. Interesting for a beginner but annoying for advanced users. Documentation should be complete. Academy and class room training are for exercises.
- Conclusion: We will not leave gaps in docs. It is more important that documentation is perceived as complete and accurate than a great pedagogic experience.
- Idea: Provide a version for beginners and a version for experts in the same page. For example, high-level steps that expand to show more detail when clicked or high-level steps that link to a more detailed procedure.
- Training material already does this. It is possible but requires a lot of editing effort and efficient content re-use.
- Table of contents already is a kind of high-level steps. If you write your headings well, an experienced user should have a lot of clue.
- Conclusion: We won't do this for now.
- Complaint: The monospaced font is difficult to tell apart from normal text. We use the Consolas font. Could use Courier instead.
- Consolas:
- Courier:
- Consolas:
Conclusion
There is no single recipe for the ideal example in documentation. It is probably a combination of speedy Git link for speed freaks and a detailed explanation for newbies. We are already very close. Refine the repice and keep repeating. 