opencms days 2014 - introducing the 9.5 opencms documentation
TRANSCRIPT
![Page 1: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/1.jpg)
Daniel Seidel, Alkacon Software
Workshop Track
Introducing the 9.5
documentation
04.11.2014
![Page 2: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/2.jpg)
● 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
![Page 3: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/3.jpg)
● How we search for information
● Implications on documentation
What should a documentation be
like? 3
![Page 4: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/4.jpg)
● 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!
![Page 5: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/5.jpg)
● 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)
![Page 6: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/6.jpg)
● 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)
![Page 7: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/7.jpg)
● 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
7
Implications on documentation (II)
How to achieve
these goals?
![Page 8: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/8.jpg)
● 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:
![Page 9: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/9.jpg)
● 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)
![Page 10: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/10.jpg)
● 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)
![Page 11: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/11.jpg)
● 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
![Page 12: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/12.jpg)
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
![Page 13: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/13.jpg)
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
![Page 14: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/14.jpg)
14
HTML documentation: Roundtrip
Site
navigation
Topic
Content
Search
option
![Page 15: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/15.jpg)
● 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
![Page 16: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/16.jpg)
16
Overview topics - Example
![Page 17: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/17.jpg)
● 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
![Page 18: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/18.jpg)
18
Content topics - Example
![Page 19: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/19.jpg)
19
Content topics - Example
Page navigation in
action
![Page 20: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/20.jpg)
● 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
![Page 21: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/21.jpg)
21
Demo topics - Example
Overview /
Related links
The result
(in a wrapper)
Interesting spots
(with code
snippets)
![Page 22: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/22.jpg)
● 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?
![Page 23: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/23.jpg)
● 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
![Page 24: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/24.jpg)
24
Search - Example
Restrict subsite
Restrict type
![Page 25: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/25.jpg)
● 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?
![Page 26: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/26.jpg)
● 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
![Page 27: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/27.jpg)
● 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/
![Page 28: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/28.jpg)
● 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
![Page 29: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/29.jpg)
● 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?
![Page 30: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/30.jpg)
● 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
![Page 31: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/31.jpg)
● 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
![Page 32: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/32.jpg)
● 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
![Page 33: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/33.jpg)
● 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
![Page 34: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/34.jpg)
● Default texts for empty containers, e.g., for
sections
34
Use of (nested) containers
Empty section
container
![Page 35: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/35.jpg)
● 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
![Page 36: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/36.jpg)
● 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
![Page 37: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/37.jpg)
● Get the modules
● Adjustments before editing
Get involved 37
![Page 38: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/38.jpg)
● 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
![Page 39: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/39.jpg)
● 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
![Page 40: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/40.jpg)
● Any Questions?
40
Any Questions?
Fragen? Questions ?
Questiones?
¿Preguntas? 質問
![Page 41: OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation](https://reader031.vdocuments.mx/reader031/viewer/2022032419/55a2b52d1a28ab0c0d8b45b7/html5/thumbnails/41.jpg)
Daniel Seidel
Alkacon Software GmbH
http://www.alkacon.com
http://www.opencms.org
Thank you very much for your
attention! 41