OpenDoc - SUSE · Colorful tables comparing KDE vs. GNOME in terms of mailinglist/forum...

OpenDocAutomating Documentation

Markus Feilner

Team Lead SUSE Documentation

mfeilner@suse.com

About me ...

Team lead at SUSE docs

OSS journalist

Linux expert since 1994

Conch diplomat

Minister (priest) of Universal Life Church

Jedi knight

Enceladus citizen #4

Owner of lunar property

Occasionally runs through doors…

“mfeilner” almost everywhere ...

OpenDoc - What is it?

Automatically spot issues in documentation

Automatically find topics that need documentationTrigger documentation when “stuff” happensRecognize, refine, rate and report issues

Offer a specialized search engineIntegrate every possible source of information

Graphical “Lists” show information in a comprehensive way

Provide an individually configurable, intuitive portal

Aproaches of the past

Activedoc• Have the community write their own books

1st generation Wikis• Get spammed, need attention, had hard times…

• Can be modern and helpful tools (see later)

Support database

Howtos→ Good old howtos reloaded: SUSE Best Practices rock!

Approaches of the past

And the Future?

Until then… a Portal?

Search engine• Indexer

• Grab new URLs

• Weight and select content

Triggers delivering input• Somewhere, something worth documenting has happened

• Collect, refine, weight, present

Portal: • (Individually configurable) Dashboard for Users, Developer, Maintainer,

Documentation people

…OpenDoc

What to find in OpenDoc …

Tasks that are just about to become problems (e.g. things discussed on mailing lists or in forums)

The “regulars” - issues that come back

Outdated stuff in documentation

New stuff that nobody understands

New stuff that nobody documented

Enterprise documentation and help

Stubs

… (add yours)

Let’s roll – please discuss

Open source communities do not write documentation.

Developers want to write code, not documentation.

Every open source project needs documentation.

Though good software should notneed documentation, proper documentation ressources are essential to attract new users.

“Modern distributions, esp.rolling releases like Tumbleweed

are moving way too fast to be properly documented.”

Nevertheless: There is a lot of data.

The Wiki

So many potential sources...

Forums

Release Notes

Git commits and comments

The documentation of a package or product, somewhere online, not only within openSUSE or SUSE, no, SOMEWHERE out there … ANYWHERE

So what?

Fact #1:

Community and documentation are a difficult couple

Fact #2:

We have a lot of information in a lot of places.

Fact #3:

It’s about finding AND presenting it.

Fact #4:

Software is changing faster than anybody can document

(see Tumbleweed)OH REALLY??!?

Fact #5:

We can do better.

Fact #5:

We can do better.

Introducing the idea of openDOC

Open QA was invented to automate a tedious, unwanted task.

Open Build Service was invented to…

Linux was invented … to scratch an itch.

Early in 2016, in a knowledge management workshop at SUSE an idea was born:

What if we could use automated triggers to collect information, changes and news on for

example Tumbleweed, refine and paste them into a modern, dynamic,

somewhat “semantic” portal?

It’s not about “another new tool”.

#1The OpenDOC portal is a presentation layer for

many other tools. It’s open.

#2The openDOC portal includes an indexing,

weighting and differentiating search engine.

Its crawler(s) search no matter which helpful new websites openSUSE, SUSE or this tiny little

new project may set up.

#3On top of the crawler, there might be “Triggers”

that act like agents and feed the openDOC portal, created by community, partners,

developers…

#4The openDOC portal shows a “list” of recent

changes, problems, questions asked or topics highly discussed or relevant or … (add yours).

#5The list is not a list is not a list.

Semantics, weighting, presentation. For example, tag clouds are also lists.

Colorful tables comparing KDE vs. GNOME in terms of mailinglist/forum discussions, time to answer, commit amounts and version release

speed… the information is already there.

Usability

Economy

Design

StandardizationRemixability

Convergence

ParticipationWidgets

CollaborationSharing

Pagerank

User Centered

Perpetual Beta

Trust

FOAF

Six Degrees

XFN

Aggregators

VC

Pay Per Click

Modularity

Ruby on Rails

SyndicationSOAP

REST

SEO

IM

XHTML

Accessibility

Semantic

XML

UMTS

Videocasting Podcasting

SVGAtom

Browser

OpenID

Wikis

Simplicity

Joy of Use

AJAX

The Long Tail

Affiliation

CSS

Web Standards

MicroformatsDataDriven

OpenAPIs RSS

Mobility

VideoAudio

Blogs

Social SoftwareRecommendation

Folksonomy

Web 2.0

(from Wikipedia) Original by Markus Angermeier Vectorised and linked version by Luca Cremonini - Based on The huge cloud lens bubble map web2.0 web20map.png Vectorised and linked version from Web 2.0 Map Web_2.0_Map.svg

Weblate: https://l10n.opensuse.org/

More Examples …

SUSE Customer Center

Reddit

Yelp, Tripadvisor

Google Alerts

(Open) Build Service

Wikidata Games

...

What’s a Trigger?

Triggers are different...

What a Trigger could be ...

A Trigger is any agent that feeds data into openDoc. Like OpenQA’s tests they are open

source, of course.

What a Trigger could be ...

Triggers qualify information from the huge haystack, like spearfishing, contributed by the

people who know.

The source for a trigger could be ...

… a mailing list thread with more than e.g. 20 mails from more than 4 different people...

A Trigger could be ...

… the standard e-mail from OBS telling you and me about the recent changes in

Tumbleweed today ...

A Trigger could be ...

… a daemon monitoring social network discussions about a topic ...

A Trigger could be ...

… a hashtag in a commit comment, … a keyword in the release notes,

… a special topic or a keyword in mailing list or forum threads,

… predefined entities in documentation, … a standard Google query,

… a RSS feed agent,… a monitoring deamon’s notifications

There’s so much more ...

… because it’s open.

A documentation “editing on its own” ? Yes it can.

Examples how to refine knowledgeAutomatic collection: • Triggers for new posts• Updating metadata (e.g. build number) via bots

Cognitive classification: • Attribution: “this post belongs to”• Mapping: links, dependencies, similar pages and topics• Post or page with high quality, important change …

Enrich content:• Missing screenshots, diagrams, videos and attachments

And OpenDoc makes proposals?

ControllingAutomatic qualification: • Missing links, orphaned and expired posts, old and not confirmed

pages, requires updating or confirmation• Displaying references and sources

Stay informed• “Follow” or assign to pages and categories• Get your own stream and task list• Get notifications and reports (new posts, weekly digest, “your article

is probably outdated”, related changes)

Wikipedia adheres to its versioning system: making edits (by humans or bots) visible and provide the possibility for roll-backs.

Archiving and deleting informationAutomatic archiving and filing: • Articles and posts older than …

Cognitive deletions:• Create intelligent deletion lists (for articles) and discussions for

admins and responsible editors

Some examples• Stack Overflow (already mentioned)• Shiftlog (a customer’s project): stream, attribution, filters,

semantic• Friseurspezial.de: search and qualifying• Translatewiki.net: task lists

AI, Big Data and stuff …Machine Learning,Neuronal networks and more buzzwords…

Knowledge sharing is not a question of technology it’s (still) a question of people and content.

What can we get out of this?

OpenDOC the Portal

Imagine an automatic AND human distillery creating, gathering and refining all this

information.

OpenDOC the Portal

The “list” allows and encourages users to

RATE (helpful?)MARK (outdated, relevant?)

KICK (not important)TAG (create relations, group, etc...)

OpenDOC the Portal

Stuff that is rated higher will be presented more often, not relevant stuff will go “down the list”.

OpenDOC the Portal

Individual preferences and search criteria can define “relevance” for single users. YOU may

be different…

What for? Docu

In an ideal world, Documentation writers could use openDOC to find out what’s |[wrong|

working|good|bad|ugly] about their project.

Release Notes

Large parts could be created automagically.

HW Certifications

Imagine success and not-success stories being collected automagically in one place, helping those who work on hardware support to refine the details.

Release Management

In an ideal world, Release Managers and developers alike could use openDOC to find out

what’s |[wrong|working|good|bad|ugly] about their project.

OpenDOC for Release Managers

The portal could include features like:... individual dashboards ... live tracking of development (OBS)... analytics like the comparison of projects or tasks (see Weblate)

OpenDOC the Gardener

The SUSE documentation team is ready to provide some hours of work every week to

“refine” the results of the triggers. One of the Doc team members will act as a “gardener”,

separating the weed from the chaff.

Questions? Action items?