OpenDoc Automating Documentation. Markus Feilner Team Lead SUSE Documentation

Transcription

1 OpenDoc Automating Documentation Markus Feilner Team Lead SUSE Documentation

2 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...

3 OpenDoc - What is it? Automatically spot issues in documentation need documentation Trigger documentation when stuff happens Recognize, refine, rate and report issues Offer a specialized search engine Integrate every possible source of information Graphical Lists show information in a comprehensive way Provide an individually configurable, intuitive portal Automatically find topics that

4 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!

5 Approaches of the past

6 And the Future?

7 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

8 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)

9 Let s roll please discuss

10 Open source communities do not write documentation.

11 Developers want to write code, not documentation.

12 Every open source project needs documentation.

13 Though good software should not need documentation, proper documentation ressources are essential to attract new users.

14 Modern distributions, esp. rolling releases like Tumbleweed are moving way too fast to be properly documented.

15 Nevertheless: There is a lot of data.

16

17

18

19

20 The Wiki

21

22

23 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

24

25

26 So what?

27 Fact #1: Community and documentation are a difficult couple

28 Fact #2: We have a lot of information in a lot of places.

29 Fact #3: It s about finding AND presenting it.

30 Fact #4: Software is changing faster than anybody can document (see Tumbleweed) OH REALLY??!?

31 Fact #5: We can do better.

32 Fact #5: We can do better.

33 Introducing the idea of opendoc

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

35 Open Build Service was invented to

36 Linux was invented to scratch an itch.

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

38 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?

39 It s not about another new tool.

40 #1 The OpenDOC portal is a presentation layer for many other tools. It s open.

41 #2 The 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.

42 #3 On top of the crawler, there might be Triggers that act like agents and feed the opendoc portal, created by community, partners, developers

43 #4 The opendoc portal shows a list of recent changes, problems, questions asked or topics highly discussed or relevant or (add yours).

44 #5 The 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.

45

46 Aggregators Blogs Pagerank XFN Audio Podcasting IM Video Mobility OpenAPIs OpenID Atom RSS Collaboration Perpetual Beta Ruby on Rails SVG Semantic Web Standards Accessibility Modularity Usability XHTML SOAP REST Joy of Use Widgets FOAF Browser Simplicity Web 2.0 Remixability DataDriven Six Degrees Social Software Sharing Convergence UMTS User Centered Participation Recommendation Videocasting Wikis Folksonomy VC Design CSS Trust AJAX Pay Per Click Affiliation Economy Standardization The Long Tail Microformats SEO Syndication XML (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

47 Weblate:

48

49 More Examples SUSE Customer Center Reddit Yelp, Tripadvisor Google Alerts (Open) Build Service Wikidata Games...

50 What s a Trigger?

51 Triggers are different...

52 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.

53 What a Trigger could be... Triggers qualify information from the huge haystack, like spearfishing, contributed by the people who know.

54 The source for a trigger could be... a mailing list thread with more than e.g. 20 mails from more than 4 different people...

55 A Trigger could be... the standard from OBS telling you and me about the recent changes in Tumbleweed today...

56 A Trigger could be... a daemon monitoring social network discussions about a topic...

57 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

58 There s so much more... because it s open.

59 A documentation editing on its own? Yes it can.

60 Examples how to refine knowledge Automatic 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?

61 Controlling Automatic 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.

62 Archiving and deleting information Automatic archiving and filing: Articles and posts older than Cognitive deletions: Create intelligent deletion lists (for articles) and discussions for admins and responsible editors

63 Some examples Stack Overflow (already mentioned) Shiftlog (a customer s project): stream, attribution, filters, semantic Friseurspezial.de: search and qualifying Translatewiki.net: task lists

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

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

66 What can we get out of this?

67 OpenDOC the Portal Imagine an automatic AND human distillery creating, gathering and refining all this information.

68 OpenDOC the Portal The list allows and encourages users to RATE (helpful?) MARK (outdated, relevant?) KICK (not important) TAG (create relations, group, etc...)

69 OpenDOC the Portal Stuff that is rated higher will be presented more often, not relevant stuff will go down the list.

70 OpenDOC the Portal Individual preferences and search criteria can define relevance for single users. YOU may be different

71 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.

72 Release Notes Large parts could be created automagically.

73 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.

74 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.

75 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)

76 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.

77

78 Questions? Action items?

79