Embed Size (px)
Citation preview
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
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?
