Open source has not just changed the way we think about creating and selling products—it has also changed the way we teach people to use those products. Smart companies no longer keep technical content under lock and key. Rather, they freely distribute information with the goal of making as many people successful with their products as possible. In this webinar, we'll look at strategies for creating and managing technical content to support open source products, including: The advantages of open content The content release cycle Tools and platforms for content distribution Enabling community participation Licensing

1. Creating and Managing Content for Open
Source Products
Jackie Wheeler
VP, Technical Content and Certification
August 15, 2017

2. Welcome!
Topics:
● The advantages of open content
● The content release cycle
● Tools and platforms for content distribution
● Enabling community participation
● Licensing
2

3. “Just open, honest
communication is
the best thing in the
world.”
- Brett Davern

4. Advantages of open content
Drives adoption
● Our goal: successful users
● Make docs and training freely available
● People still buy training
4

5. Advantages of open content
● Allow users to learn about features and products they don’t already
have
● People still buy professional services to implement those solutions
Drives expansion
5

6. Advantages of open content
● More readers -> more feedback
● People still buy Tech Support
Improves quality
6

7. Content release cycle
Plan
Write
Test and
review
Release Feedback

8. The content release cycle
● Use feedback to plan content improvements at the start of each
release cycle
● Check bug database, forums, etc.
● Make in-progress docs publicly available
Get feedback early and often
8

9. The content release cycle
● Plan content for docs, training materials, articles, and blog posts
● Train users on how to use the software AND the docs
● Link articles and blogs back to docs
● Best practices
Categorize content types
9

10. The content release cycle
Write for wide audience
● Write for non-native English speakers
● Simple, concise sentences
● Define terms and acronyms
● Answer the question “why?”
● Point off to outside resources
10

11. The content release cycle
Test and review
● Test everything on multiple platforms
● Get reviews from subject-matter experts and newbies
● Get feedback from users again
11

12. The content release cycle
Release
● Release content at each milestone (if using Agile) to maximize
feedback
● Keep editing existing docs after new release has started (if allowed)
12

13. Tools and platforms

14. Tools and platforms
Github
● Github Pages is great solution for smaller doc sets that aren’t
versioned
● Docs can live with the code
● Author in Markdown or HTML
● Can keep docs in separate repository to avoid problems with
non-committers, editing after release
https://pages.github.com/
14

15. Tools and platforms
Confluence
● Free for open source projects
● Cloud and Server versions
● Many features and plugins
● WYSIWYG editor and source editor
● Scroll Versions plug-in handles versioning without losing SEO
● Scroll Viewport plug-in allows greater control over look and feel
https://www.atlassian.com/software/confluence
15

16. Tools and platforms
ReadTheDocs.org
● Free if you display an ad
● Pulls Markdown and reStructured Text content from Github,
automatically builds docs
● Provides versioning, multi-format generation (PDF, epub, etc.)
● Provides some basic templates, or create your own
https://readthedocs.org/
16

17. Tools and platforms
mkdocs
● Works with Python config to generate HTML docs from Markdown
● You can use the ReadTheDocs theme or create your own
http://www.mkdocs.org/
17

18. Tools and platforms
Asciidoctor
● Asciidoc is a lightweight markup language like Markdown
● Asciidoctor replaces the original Asciidoc Python processor
● Generates HTML 5 and includes default templates
● Open source
http://asciidoctor.org/
18

19. Enabling community participation

20. Enabling community participation
Make it easy
● Community page
● Feedback links in docs
● Forums
● Hackathons and bug hunts
● Conferences
20

21. Enabling community participation
Make it rewarding
● Points, prizes, public recognition
● Personal communication
21

22. Enabling community participation
Play to their strengths
● Developers like to write tutorials
● Architects like to draw diagrams
● Business users like to provide use cases and scenarios
● Writers like to report typos
22

23. Licensing your
content

24. Licensing
Creative Commons
24
Public Domain
(CC0)
No restrictions
Attribution (BY) Must give credit to author
Attribution (BY)
+ Share-alike (SA)
Must give credit to author and can redistribute only
with identical license
https://en.wikipedia.org/wiki/Creative_Commons_license

25. Next steps

26. Next steps
● Promote open content in your organization
● Build feedback into your content release cycle
● Try out tools and platforms
● Enable community participation
● Review licensing
26

27. Questions?

28. THANK YOU
wso2.com