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

Google

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