OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation
3 likes733 views
The document discusses the new 9.5 documentation for OpenCMS, emphasizing the importance of making documentation user-friendly and easily searchable. It introduces the concept of 'eppo' (Every Page is Page One) for structuring content to enhance information foraging and usability. The presentation highlights the evolution of the documentation and the use of new features like nested containers and element views to improve the user experience.
![●Content snippets are hard to find if reused
●Idea: Automatically provide meaningful titles
●Implementation: Mappings with macros and default values
●Example: Section titles
36
Use of mappings
<mappings>
<mapping element="Title" mapto="property:Title"
useDefault="true" />
</mappings>
<defaults>
<default element="Title"
value="%(page_title)%(no_prefix: - )
%(value:Headline[1])" resolveMacros="false"/>
</defaults>
documentation-section.xsd](https://image.slidesharecdn.com/opencmsdays2014-opencms95documentation-141127053706-conversion-gate02/85/OpenCms-Days-2014-Introducing-the-9-5-OpenCms-documentation-36-320.jpg)
OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation
- 1. Daniel Seidel, Alkacon Software Workshop Track Introducing the 9.5 documentation 04.11.2014
- 2. ●What should a documentation be like? ●Introduction to the new 9.5 Documentation ●OpenCms features: How they are used in the documentation ●Getting involved ●Summary Overview 2
- 3. ●How we search for information ●Implications on documentation What should a documentation be like? 3
- 4. ● Where do you look for answers ● … trying to find a software that fits to your needs? ● … stuck with a specific problem? 4 If you need information … Google it Man pages First you will ask Google!
- 5. ●Very short summary: ●We take what is easy to get and looks good ●We stop searching immediately when our “hunger on information” is satisfied, or we are tired of searching 5 Information foraging People do not search for information with the intellect of a research librarian, but with the nose of a predator (EPPO, page 1)
- 6. ●The web is the documentation ●We search where finding results is promising: Searching online is easy ●We are “always” online – so the web is present always ●The answer to a question, or the documentation to a product is what Google finds first (if it is sufficiently “tasty”) ●“Everyone” writes documentation for your product (think e.g., of Stack Overflow, blogs, forums, …) 6 Implications on documentation (I)
- 7. ●Try to make users read your documentation! ●make foraging easy, i.e.: ●Navigation should be easy inside the documentation ●Information in completely “tasty” bits ●Your documentation should become the first hit on Google 7 Implications on documentation (II) How to achieve these goals?
- 8. ●Hard to find or (physically) get ●Big information piece (tasty bits hidden?) ●Hard to forage for information (hierarchical structure, sequential dependencies) ●The way of reading is determined by the author, not by the reader 8 Implications on documentation (III) ●Books/PDFs have several disadvantages:
- 9. ●Promising approach: EPPO (Every Page Is Page One) ●Topic-based writing ●EPPO Topic = a single web page ●Each EPPO Topic should … ●Self-contained ●connected, but not dependent on other topics ●Specific and of limited purpose ●task-based, not feature-based ●content should provide decision support ●Conform to a type ●Document similar things in a similar style ●Determine a “best way” to describe a certain thing 9 Implications on documentation (IV)
- 10. ●Each EPPO Topic should … (continued) ●Establish context ●Reference related topics ●Reference also sources outside of your documentation ●Assume the reader to be qualified ●Avoid lengthy introductions ●Tell what you assume – and where a reader can get this knowledge ●Stay on one level of abstraction ●Provide topics on different levels of abstraction ●Link at points where the reader may want more details or the bigger picture ●Link richly ●Whenever something might explanation: link! ●Purpose: keep the reader reading and away from Google – take him were you want him to go 10 Implications on documentation (V)
- 11. ●Documentation before 9.5 ●Documentation now ●Roundtrip through the documentation ●What’s new content? ●How to get the documentation? ●The TLDDoc Introduction to the new 9.5 Documentation 11
- 12. 12 The Documentation before 9.5 Wiki •Varying quality •Outdated information Dev-Demo •Interactive examples •Shipped with the demo Tutorial •Very basic •For editors •Included in demo Demo •“What is possible”-demo •No background info JavaDoc •Detailed API documentation PDF/Word •Book-like •For developers
- 13. 13 The 9.5 Documentation Wiki •Varying quality •Outdated information Dev-Demo •Interactive examples •Shipped with the demo Tutorial •Very basic •For editors •Included in demo Demo •“What is possible”-demo •No background info JavaDoc •Detailed API documentation PDF/Word •Book-like •For developers Extended by TLD documentation Greatly extended
- 14. 14 HTML documentation: Roundtrip Site navigation Topic Content Search option
- 15. ●Alternative dimensions to the site navigation ●Link to related topics ●Starts with an overview (dimension description) ●Links to external resources allowed ●Teasers for topics ●Grouped links ●Examples: ●Introduction ●Content in OpenCms 15 Overview topics
- 16. 16 Overview topics - Example
- 17. ●All the same structure: ●Introduction / Overview ●Related links ●Various sections ●Page navigation (icon on the right-hand side) ●Aim to conform with EPPO guidelines: ●Establish context ●Link richly ●Specific, limited purpose ●Assume the reader qualified ●Self-contained ●One level of abstraction ●Conform to type 17 Content topics
- 18. 18 Content topics - Example
- 19. 19 Content topics - Example Page navigation in action
- 20. ●Allow interaction (mostly if offline) ●Are special content topics ●Generally the same structure (Overview, related links, sections) ●Special section structure: ●“The result” ●“Example resources and interesting spots” ●Special resource types used ●Demo wrapper ●Resource view 20 Demo topics
- 21. 21 Demo topics - Example Overview / Related links The result (in a wrapper) Interesting spots (with code snippets)
- 22. ●Site navigation: ●Just browse ●Searching something you can not name correctly ●Search: ●Specific question ●Finding something again ●(Related) links: ●Changing level of abstraction ●Finding related information ●Overview topics: ●Alternative sitemaps 22 How to navigate?
- 23. ●Search option present on every page (magnifier in the upper right corner) ●Default demo search is used ●You find more than you might want ●Restrict results to subsite “Documentation” ●Restrict results to type “Container page” ●(separate search page may be added in future versions) 23 Searching the documentation
- 24. 24 Search - Example Restrict subsite Restrict type
- 25. ●Introduction topics ●Background topics ●Administration topics (most) ●Server installation ●Development setups ●(Traditional) workplace description ●Many topics on content type definition ●Caching in OpenCms ●Some demos (Advanced container usage, dependent editor fields) ●Improvements to existing topics ●Description of the new features 25 Very new structure, but new content?
- 26. ●Included in the default installation ●Needs the demo modules ●Available online (after the OpenCmsDays) 26 How to get the new documentation? Online Local Google it! Get the most out of the demos
- 27. ●OpenCms ships with it’s own tag library ●All tags and functions are described in a TLD (Tag Library Descriptor) ●A JavaDoc-like documentation of the TLD is online now: ●Particularly helpful when writing JSPs (if you do not have help via your IDE) 27 The TLDDoc http://files.opencms.org/javadoc/tld/
- 28. ●What new features are used? ●Excursion: The editor tools ●Use of element views ●Excursion: Content structure ●Use of (nested) containers ●Use of template models OpenCms features: How they are used in the documentation 28
- 29. ●Documentation uses a lot of new features: ●Nested containers ●Element views ●Template models (with copy-option) ●Body of <cms:container> tag ●Mappings with defaults and macros ●Additional editor tools available ●Special view on the documentation ●Exploration of meta-data 29 What new features are used?
- 30. ●Extra modules ●Not included in the default installation ●Add special content tools ●Adjust appearance of documentation pages 30 Excursion: The editor tools In the following demos, the editor tools will be installed
- 31. ●Problem: ●Documentation is used offline for the demos ●Documentation content should not be visible, demo contents should ●Solution: Element views ●Default view: Demo contents ●Editor element view: Documentation contents ●Special in the documentation ●Rights management does not fit, for most users are logged in as Admin ●Work-around: Dummy content 31 Use of element views
- 32. ●Topic in one-to-one relation to pages (EPPO) ●Content of a topic structured as ●Sections ●Several content snippets: ●HTML, Code, Figure, Definition List ●Advantages ●Easy editing (avoid contents with very complicated structure) ●Clear representation of available content elements ●Disadvantages in semantic relation 32 Excursion: Content structure
- 33. ●Containers and their types are mainly used to force a special structure 33 Use of (nested) containers "documentation-topic" "documentation-content" "documentation-section" There fits only one single topic Only sections fit here All content- snippets must be placed in sections
- 34. ●Default texts for empty containers, e.g., for sections 34 Use of (nested) containers Empty section container
- 35. ●Idea: Enforce topic structure by templates ●Three models ●Default page ●Overview page ●Demo page ●Use of copy function ●Topic content already placed on new pages ●First section ●Use of reuse function ●Demo content wrapper 35 Use of template models
- 36. ●Content snippets are hard to find if reused ●Idea: Automatically provide meaningful titles ●Implementation: Mappings with macros and default values ●Example: Section titles 36 Use of mappings <mappings> <mapping element="Title" mapto="property:Title" useDefault="true" /> </mappings> <defaults> <default element="Title" value="%(page_title)%(no_prefix: - ) %(value:Headline[1])" resolveMacros="false"/> </defaults> documentation-section.xsd
- 37. ●Get the modules ●Adjustments before editing Get involved 37
- 38. ●Get the modules ●All modules will be hosted on GitHub ●Get the modules from there if you write at the documentation ●When you add content ●Change the sitemap configurations, such that your contents use a separate name scheme (avoid merge conflicts) ●More information will follow ●Possibly “easier” ways to edit may follow 38 Get involved
- 39. ●We search for information like animals for food Documentation must fit to this behavior ●The new OpenCms Documentation accounts for information foraging ●Online available ●Structured in EPPO topics ●Searchable ●The TLDDoc is online now 39 Summary Every Page is Page One: Topic-based Writing for Technical Communication and the Web by Mark Baker, XML Press 2013, ISBN 978-1-937434-28-1
- 40. ●Any Questions? 40 Any Questions? Fragen? Questions ? Questiones? ¿Preguntas? 質問
- 41. Daniel Seidel Alkacon Software GmbH http://www.alkacon.com http://www.opencms.org Thank you very much for your attention! 41