The open source way is about applying the principles of open source software development beyond software. Why then should we apply separate rules to our documentation? This was the question I asked when joining the Content Services team at Red hat. In this session, we will discuss common documentation practices for companies supporting open source software. Then I will introduce you to the tools and processes developed by our documentation teams to work using the open source way. After this session, you'll be able to take our lessons learned and our collaboration framework to assist in writing documentation in the open source way for your product.

1. DOCUMENTATION
THE COMMUNITY WAY
Texas Linux Fest 2018 | Austin, TX
Nicole C. Baratta
Content Strategist
9 June 2018

2. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com2
WHO AM I?

3. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com3
WHO ARE YOU?
● Do you work in documentation?
● Do you work in the upstream?
● Do you work for a company?

4. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com4
● Customer Content Services (CCS) at Red Hat creates product
documentation and other supporting content for the customer.
● The Content Strategist leads the creation and implementation of a
comprehensive strategy that defines content deliverables to support
key business objectives and defines recommendations with a focus
on feedback from customer-facing stakeholders.
CUSTOMER CONTENT SERVICES

5. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com5
RED HAT AND COMMUNITIES
We believe the best software is made in the open
https://www.redhat.com/en/about/development-model

6. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com6
● Very few would work directly in the upstream when it came to
documentation
● Writers might copy snippets of documentation from upstream &
paste it into downstream docs
● Some would use the upstream as reference and write fresh
documentation downstream
● Others would submit occasional patches upstream while writing
downstream
HOW WE WERE DOING THINGS
Each project is different

7. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com7
● Created a guide to help enterprise writers navigate open source
communities
● Working on adjusting our documentation model to think of docs as
code!
● Educate writers about how they can use version control (git) to
manage collaborative documentation efforts
● We needed to introduce writers to open source sooner!
ENTERPRISE TECHNICAL WRITERS
Many haven’t worked with open source before

8. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com8
ONE SAMPLE WORKFLOW
#2
Community Doc Repos
#6
Merged to CCS Git Repos
#1
Community
/ RH Dev
written
content
#3
Content
Strategy
#5
CCS/SME Edit for
Voice, Grammar,
and Accuracy
#4
CCS writes
original content
or copies
community
content
#8
Docs Published to Customer Portal
#7
QE
Review
Sometimes contributed
back to community

9. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com9
PROPOSED WORKFLOW
#5
Merged to Community Doc Repos
#5
Merged to CCS Git Repos
#2
Community
written
content**
#2
CCS written
content**
#1
Content Strategy
#3
CCS/SME Edit for
Technical Accuracy,
Grammar, and
Voice
** Include tags to note features we don’t support
#6
Docs Published to Portal
#2
RH Dev
written
content**
#4
QE Review

10. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com10
● Created a committee to share experiences (successes and failures)
● Outlined commonly asked questions and concerns
● Compiled best practices
● Published to GitHub for anyone to contribute to
○ Join us: git.io/vh2KJ
HOW DO WE GET THERE?
Start with a framework

11. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com11
● Created a 100 point evaluation to decide if both the community and
the enterprise are ready to work together on docs.
○ git.io/vh2oF
● Included basic instructions for collaborating with an existing
community
○ git.io/vh2oN
START WITH COMMUNITY BASICS
Teach folks the basics of joining open source communities

12. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com12
● Cover basic etiquette
○ git.io/vh2oN
● Offer suggestions for repository structure (or tips for repository
migration)
○ git.io/vh2Ke
○ git.io/vh2ox
JOINING (OR CREATING) A COMMUNITY
Instruct people on how to join or create an open source community

13. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com13
● Agree upon a markup language
● Agree upon a publishing tools
● Agree upon a directory structure
○ Will you work in the same repo as code or separate
● Agree upon governance structure
● Modular documentation for easy picking & choosing
● Define a review/testing process
● Compromise!
BEST PRACTICES
Suggestions compiled from working with several communities

14. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com14
● AsciiDoc for documentation markup
○ More lightweight than DocBook and more robust than MD
○ Allows for modular documentation content structure
○ Uses attributes for easy customization of docs
● Github upstream and GitLab downstream
● A series of homebrewed scripts to process mirroring, building, and
publishing documentation
○ Considering swapping these with Antora in the new future
● Drupal for presenting and searching our documentation
OUR PICKS
What we use to create documentation at Red Hat

15. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com15
● https://gohugo.io
○ Kubernetes example: https://kubernetes.io/docs/
● https://antora.org
○ Fedora considering
https://bex.fedorapeople.org/antora-test/fedora/rawhide/install-guide
● http://www.sphinx-doc.org/en/master/
● https://www.gitbook.com
● http://asciibinder.org
TOOLS FOR PUBLISHING DOCS
Tools that you can use to publish your documentation to your community site

16. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com16
● Join our mailing list
○ git.io/vh2KT
● Join us on GitHub
○ git.io/vh0An
● Submit issues/suggestions/questions
○ git.io/vh2KL
PARTICIPATE
Join our community to share your tips with the world

17. Nicole C. Baratta | @ncbaratta | ncbaratta@redhat.com17

18. THANK YOU
linkedin.com/in/ncbaratta/
youtube.com/user/RedHatVideos
facebook.com/ncbaratta
twitter.com/ncbaratta