Page tree
Skip to end of metadata
Go to start of metadata

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 hand2) Download configuration as XML3) Clone the complete module
Effective learning(tick)(tick)(tick)(error)
Convenience(error)(error)(question)(tick)(tick)
Pros Helps you understand componentsFast
ConsError-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:

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. (thumbs up)

 

  • No labels