Documentation of OpenCms will be better than ever with the release of version 9.5. OpenCms 9.5 documentation has been revised and greatly extended. Moreover, a new approach has been taken in writing the documentation directly inside OpenCms. Being HTML based, it allows the content to be found easily through online search engines for quick reference. It also allows combining the documentation with interactive examples and demos. In this session, Daniel introduces the new documentation. He focuses on the content of the documentation, and provides an overview about the main areas of improvement. He also explains briefly the technical structure of the documentation, which makes use of OpenCms 9.5 features such as nested containers. Last but not least, he points out opportunities for future collaboration to document OpenCms even better.

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