OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation
-
Upload
alkacon-software-gmbh -
Category
Software
-
view
195 -
download
0
Transcript of OpenCms Days 2014 - Introducing the 9.5 OpenCms documentation
Daniel Seidel, Alkacon Software
Workshop Track
Introducing the 9.5
documentation
04.11.2014
● 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
● How we search for information
● Implications on documentation
What should a documentation be
like? 3
● 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!
● 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)
● 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)
● 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?
● 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:
● 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)
● 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)
● 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
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
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
HTML documentation: Roundtrip
Site
navigation
Topic
Content
Search
option
● 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
Overview topics - Example
● 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
Content topics - Example
19
Content topics - Example
Page navigation in
action
● 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
Demo topics - Example
Overview /
Related links
The result
(in a wrapper)
Interesting spots
(with code
snippets)
● 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?
● 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
Search - Example
Restrict subsite
Restrict type
● 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?
● 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
● 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/
● 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
● 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?
● 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
● 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
● 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
● 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
● Default texts for empty containers, e.g., for
sections
34
Use of (nested) containers
Empty section
container
● 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
● 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
● Get the modules
● Adjustments before editing
Get involved 37
● 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
● 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
● Any Questions?
40
Any Questions?
Fragen? Questions ?
Questiones?
¿Preguntas? 質問
Daniel Seidel
Alkacon Software GmbH
http://www.alkacon.com
http://www.opencms.org
Thank you very much for your
attention! 41