Fedora Flock 2015 - Organized Chaos (Technical Writing)

Organized Chaos, Technical Writing

Led by two representatives of the Fedora Docs team, Brian Exelbierd & Pete Travis

#startmeeting

#topic topics of the talk
1) New Contributor Experience
2) The Ideal Solution

#topic New Contributor Experience

1) What should I do to get involved?
Write about whatever you’d like!
- Overwhelming opportunities, no hints, no tasks waiting to ‘cut their teeth’ on
- Onboarding is blocked until the new contributor picks a topic that’s right for them
- Many ideas aren’t good or are too simple or too complex or inappropriate
- Content from blogs and notes doesn’t have an easy fit

2) Wherever it fits! …or not
- Established guides have a well-defined scope
- Starting a new Guide is Big Deal
- Publishing is delayed
- Example being the Docker example: starting a new Guide is a big deal because before a new guide is established, a lot of content is required to make it a complete product

3) Who can help you?
The experienced, proficient technical writers on the docs team can through:
- Broadly responsive mailing list
- Active IRC channel
- Workshops available twice a week during “Office Hours”

4) What do you need to get involved?
Common Tools: Publican, docbook, editors, xmllint, git
- Docbook is not easy to be good at; harder to be proficient
- Publican renders well but can be confusing
- Syntax highlighting? Tag completion? Validation? Be prepared to spend time on setup.
- `xmllint` error reporting is not intuitive
- Legacy website, broken dependencies
- Git allows collaboration, peer review, change management, more
Learning the tools can be hurdle but is needed to contribute meaningfully

5) How do I write well?
Context, detail, direct language
- Most valuable resource available from the Docs team
- Review process is dominated by tooling and markup
- Often omitted to avoid continuing a negative feedback loop

#topic The Ideal Solution
1) Documents go through a predictable, staged life cycle
2) Multiple markup formats are supported
3) Peer review focuses on content quality
4) Publishing happens automatically
5) Submission and retrieval of translations happens automatically
6) SIGs and teams can “own” content and get support
7) Provides a home for internally facing content
8) Documentation can be generated via programming, if appropriate

#topic The New Model (Pipeline)
1) Idea
- Want to see documentation for a project or software
2) Draft
- Someone will be able to write documentation for it
- Rough draft composed
3) Review
- Peer review process
4) Revision
5) Translaton
6) Publication

#topic How do I contribute?
1) Drive-By Submission
- Modular, pick up what you can
2) Protégé
- In-depth, comprehensive writing
- libvrt Python documentation example

#topic Summary
1) Contributor experience needs to be improved
2) Tooling is insufficient to publish today and doesn’t support change
- Workshop on Friday @ 5pm
- Git structure (pagure, may mostly be confirming functionality / configuration)
- Process for triggered publishing / testing (this has been started with buildbot)
- Sub tasks to create builders based on the specific markup (docbook first)
- Visual design and meta site builder (needs help)
3) Drive by / low commitment contributions are required for growth