Full FAD Details:
https://fedoraproject.org/wiki/FAD_Documentation_2016

IRC: #fedora-docs on Freenode
Blue Jeans Dial-in: (888) 240-2560 USA toll free; see https://bluejeans.com/numbers for other dial in numbers

    Conference code: 97839 21014

Blue Jeans Video: http://redhat.bluejeans.com/pfrields

Telegram: (Web, Linux Client, and Mobile App)
     Location: Red Hat Tower, Raleigh, NC 
     Date: May 6-8, 2016 
     Personnel (people who might fit the bill) 
     Name (location, role) Confirmed? (Y/N)
     Pete Travis (location?, Fedora docs team lead) Confirmed? (Y)
     Zach Oglesby (Baltimore MD, Fedora docs team member) Confirmed? Y
     Jared Smith (Fredericksburg, VA, Capital One) Confirmed? Y
     Shaun McCance (Cincinnati, Red Hat community docs) Confirmed? Y
     Stephen Gilson (Westford, Red Hat product docs) Confirmed? (Y)
     Paul Frields (Fredericksburg VA, Red Hat Fedora eng) Confirmed? Y
     Ryan Lerch (Brisbane QLD Australia, Red Hat Fedora eng) Confirmed? Y
     Silas Hensley (Brno, Red Hat product docs) Confirmed? Y
     Remy DeCausemaker (Raleigh, Red Hat OSAS/Fedora community lead) Confirmed? Y
     Jim Perrin (Houston Tx, CentOS Project) Confirmed? (Y)
    Nick Bebout - Remote
     Glen Rundblom (Champaign, IL, Fedora docs team member) - Cannot Travel in May but would like to contribute / be apart in some manner
     Stephen Wadeley (Brno, Red Hat by day, Fedora docs team member by night) - Unfortunately I will be traveling that weekend, holiday already booked.
     Karsten Wade (Santa Cruz, CA; former Fedora Docs Lead) - Interested in helping remotely, at least in a history-of session, & in discussions around CentOS & workflow.
     others?
    Kushal (remotely, while he can stay awake :)
    Tummala Dhanvi - c0mrad3 (remotely) 
    Corey Sheldon (linuxmodder) --remote

     Other considerations 
        Paul would drive to RDU and could give Jared a lift, and/or pick up someone at the airport. Paul must leave the afternoon of  Saturday, May 7. 
    Meals/Social Events
    Friday Lunch
        Mellow Mushroom Delivery (pizza)
    Saturday Lunch
        Jimmy John's: https://www.jimmyjohns.com/download/jj_menu_no_prices.pdf
    Friday Night Dinner (Shaun)
        The Pit + BoxCar + Circa 1888 http://www.thepit-raleigh.com/
    Saturday Night Dinner (decause)
        The Big Easy - Dinner Menu - http://media.wix.com/ugd/58d9b0_bd7159b8546f4d86b0093f46f3b27fb4.pdf
    Sunday Lunch
        Jet's Pizza 

Friday May 6th Agenda (all times in EDT, UTC-4)

  The goal for day 1 is to figure out the workflows we need to support
  for the best possible engagement across all the people involved.

* 09:30am - Arrive at lobby at Red Hat Tower -- I'm working with Remy
            so we can get everyone into the building appropriately.
            We have the "Fedora" room on 9th floor reserved, which is
            publicly accessible.
* 09:45am - Introductions, get acquainted
* 10:00am - Go around the room and state your meeting goals, pain
            points, what skills/resources you bring to the FAD
* 11:00am - Map out high level user stories (we may have some already)
            -- I would ask that we *AVOID* any talk about any specific
            tools, markup, or implementation until done with this
* 12:30pm - Lunch
* 02:00pm - Finish user stories
* 04:00pm - Start discussing currently available tools and the user
            stories they either hit or miss
* 05:30pm - end of day(ish), depending on how discussions go -- record
            a "report out" on activities for community transparency
* 06:30pm - dinner somewhere TBD

Day Report : https://bluejeans.com/s/9Bgg/ 

Saturday May 7th Agenda
  The goal for day 2 is to come to an agreement across all involved on
  the tools needed to achieve the workflows we described on day 1.

* 09:30am - convene, continue tools talk
* 12:30pm - Lunch
* 02:00pm - Ideally, we have reached a point we agree on a tools
            strategy.  If not, this day continues until done!  If so,
            we can move on to mapping out any system changes,
            infrastructure work, enhancements, or features that
            someone needs to create; and assign each of these with a
            due date to someone.
* 06:00pm - end of day(ish) -- record "report out"
* 07:00pm - dinner somewhere TBD

Requirements Vetting Grid: https://ethercalc.org/txnb0f8lewsz
Day Report: https://fedorapeople.org/groups/docs/fedoradocsfad2016-day2-reportout.webm


Sunday, May 8th Agenda


  The goal for day 3 is to hack on things while we're f2f.  This
  should be done in a concerted, sprinty way (e.g. cards) to avoid
  getting off topic or otherwise wasting time.

Have 5-7 Topical Areas
    Installation
    Networking
    Sysadmin
    Storage
    Desktop
    Identity
    Power Management

Tickets:
    Existing Repos

    New Pintail Instance deployed to http://docs.fedoraproject.org

    Overall:
    X purge and rewrite meta-documentation about "how to write docs for Fedora"
    X decide on orchestration layer
    X decide on publishing layer
    X Anon Pull Requests in pagure?

    asciidoc pintail - Topic Based 
    X pintail cfg
    X ansible playbooks
    X packaging pintail
    X package the asciidoctormallard
    X docbook to asciidoc conversion
    X staging environment for asciidoc-pintail
    X present information architecture to the fedora-docs list and community
    X publishing of translations


    docbook pintail - Book Based
    X get the docbooks, as books, published into pintail
    X Theming of docbook-pintail site
    X edit to docbooks to work with pintail
    X publishing of translations

    book to topic conversion
    X Model for conversation of books to topics presented by sgilson
    X 4 week "Sprints" for each book to be presented during Docs meetings
    X Create a 'map' of topics that get chained together per book
    X create a list of books to be converted to maps


Modularity Background Info:

    https://communityblog.fedoraproject.org/modularity-use-case-application-independence/
    https://fedoraproject.org/wiki/Modularization
    https://fedoraproject.org/wiki/Modularity_Working_Group
    http://taiga.fedorainfracloud.org/project/modularity/


User Stories:
    Personas: https://fedoraproject.org/wiki/Docs_Project_Focus

Problem Statement:
    New contributors need to know "what needs to be written about?"


Anatomy of a User Story:
    "As a user role, I want to create some goal, so I can reach it"


Examples: 

https://twitter.com/GoatUserStories
https://twitter.com/JediUserStories

    1) Content Strategist
    2) New Docs Contributor
    3) Experienced Docs Writer
    4) RH Content Professional
    5) Drive-by Fixer
    6) Reader
    7) Publisher
    8) Tools Maintainer
    9) Subject Matter Expert
    10) Translator


For example:

    As a Reader, I want to read the docs on my mobile device so I fix my install.
    As a Reader, I want to link to specific regions of the docs so I can share questions/answers.
    As a Reader, I want to get specific answers to questions for my current release so i can fix my problems.
    As a Reader, I want to ...


Case-Study: Experienced User (Ian Kelling)

	I've tried fedora a few times over the years. I recently met Remy (fedora
community lead) at oscon and he convinced me to give it another try and give
some feedback. This is meant to be constructive, just my impression, I could be
missing things.


	I google "fedora firewall", because I'd like to learn generally about it,
how to do a few common things like opening a port, or forwarding something. I
see links to official fedora docs. So I think, yes, lets rtfm!


    link 2:

    2.8.2. Basic Firewall Configuration - Fedora Documentation

    https://docs.fedoraproject.org/.../Fedora/.../sect-Security_Guide-Firewalls...


    (click link, it's fedora 11 doc)


    link 3:

    3.8.13. Configuring the Firewall - Fedora Documentation

    https://docs.fedoraproject.org/.../Fedora/.../sec-Configuring_the_Firewall....


    (click link, it's fedora 19 doc)


    link 4:

    3.8.9. Disabling firewalld - Fedora Documentation

    https://docs.fedoraproject.org/en.../Fedora/.../sec-Disabling_firewalld.htm...


    (click link, it's fedora 20 doc)


    link 6:

    16.7. Firewall Configuration - Fedora Documentation

    docs.fedoraproject.org/.../Fedora/.../s1-redhat-config-kickstart-firewall.ht...


    (click link, its fedora 20 doc)


    So... now I really want to know if fedora 22 doc has a section on

    firewall.


    I see the url's all look like this:

    https://docs.fedoraproject.org/en-US/Fedora/19/html/Security_Guide/sec-Configuring_the_Firewall.html,

    so I try changing the 19 to 22, but it takes me to

    https://docs.fedoraproject.org/en-US/index.html.


    So then I look for a search feature. I don't see one. So then I expand the
fedora 22 drop down, and I see 7 high level categories with no obvious right
place, so now I'm fairly confused as to how to find stuff.


    So I search firewall on google
site:https://docs.fedoraproject.org/en-US/Fedora/22. And the closest thing I
see is the #1 link, 14.15. Configure the Firewall to Allow Incoming NTP
Packets. But I'm wondering if there is a general section like link 2 or link 3
from the original google search, so I click around some more, I figure there
are 4 of the 7 sections in the sidebar which could cover firewall: installation
guide, networking guide, selinux users and administrators guide, and system
administrators guide. So I click on administrators guide, (and I'm slightly
surprised to find a comprehensive table of contents, as the ui design of left
menu sort of implied that it was THE table of contents, not that there was more
useful list of sections within. Why couldn't I see those things in the
expandable menu?). I do a word search, find the ntp related link I saw before,
repeat for the other 3 sections, find one in the installation section which
looks generic, only learn that installation has a limited set of firewall
configuration options and this is not what I'm looking for. So I'm deciding
there is no general firewall documentation for 22.


    So now I look back at the best link I originally found,
https://docs.fedoraproject.org/en-US/Fedora/19/html/Security_Guide/sec-Configuring_the_Firewall.html,
and I think, yes, I'm confirming my original impression that this is really the
kind of documentation I was looking for, but I'm reallyconfused and frustrated:
does any of this still apply? did they abandon firewall-config? What's the
story?


    I've had this same experience several times with fedora, and at this point
I've mostly given up frustrated and annoyed.


    Once, when I was feeling a bit more ambitious, I thought. Hmm, maybe I can
help out on docs, cuz I have noticed the new links like "click to contribute to
fedora!" So click through, quickly get to this page:
https://fedoraproject.org/wiki/Join_the_Docs_Project


    Well, after 15 minutes of reading lots of stuff I'm not interested in, I
can't find the source code to the fedora 22 official docs, or anything about
how to improve them, and I think, I'd have gotten way more done by just going
to the arch wiki firewall page, and I could have just hit edit and improved the
thing.


    Suggestions: make previous fedora version documentation link to the relevant
current documentation because google links to old docs are the reality for most
fedora searches, or if there is no newer, say that, and say whether this is
still relevant to newer distros. And port documentation forward, it seems there
is lots of good documentation sections which only exist for older fedora
versions. Make contributing to the official docs possible in some short amount
of time. Make a search feature (this is 2015), even if it's just to some 3rd
party search engine (google site search gave me good results).


    Oh, and how about filing a bug? First google link: "How to file a bug
report - FedoraProject" https://fedoraproject.org/wiki/How_to_file_a_bug_report
It's like a horribly bad novel when I wanted a tldr for any reader who's filed
bugs before for free software projects and wants to file one for fedora:


    Up top, "Documentation Summary:", doesn't try whatsoever to summarize "how
to file a bug report", but just talks about meta things about the document,
complete waste of my time.


    1st section after the fake summary: "How to File a Bug Report", first
sentence: "This page describes a procedure for reporting software bugs to
Fedora developers." Well, I'm not a fedora developer, so this isn't for me?
Well, I don't see any other way to file a bug sooo, does fedora accept bug
reports from it's users? And it's redundant, making it just bad quality
writing, leaving a bad impression, and making me think no one actually reads or
improves this page. Significant chunk of new users are giving up at this


    Ok, this is a wiki, so let's try and edit this page. Click log in, which
leads to this page this page:
https://fedoraproject.org/wiki/Account_System?rd=Infrastructure/AccountSystem,
which is a novel length page which as far as I can see does not actually lead
to getting a wiki account! No wonder no one edited the page, creating a wiki
account if a total nightmare! Suggestion: fix that.


    Ok, flash back to the filing a bug wiki page. Next sentence: 'A bug is
defined as "an error, flaw"'..., am I doing a homework assigment? This document
is called "how to file a bug report", not spend an hour reading wikipedia. Ok,
next sentence says this is about https://bugzilla.redhat.com/, let's skip to
the chase and try using that, because the rest of this document looks pretty
useless.

    Go there, and see from the 1st sentence.: "Thank you for visiting Red Hat
Bugzilla. Red Hat Bugzilla is the Red Hat bug-tracking system and is used to
submit and review defects that have been found in Red Hat distributions." Ok,
so am I at the wrong place? This is confusing.  Is fedora a "a red hat
distribution"?  I skim a bit more...  "If you are a Fedora Project user and
require assistance, please consider using one of the mailing lists we host for
the Fedora Project. " Well, I'm filing a bug to get "assistance" in it being
fixed, so it seems I should post it on the mailing list instead?

    So, wondering if fedora is a red hat distribution, I remember that there is
a link on the main fedora page "Learn more about the relationship between Red
Hat and Fedora »." So I go there. It's not very helpful, its not well written
to stand on it's own. The first section goes like this "jill makes pizza for
anyone. John makes pizza for big companies. People go to jill in order to
collaborate with john. Businesses love john's pizza. The end. (notice a gaping
hole?  Why would someone go to john in order to collaborate with jill? And tt's
pretty relevant title of the page.). Anyways, this one is a minor gripe
compared to the rest, but my suggestion is to replace it with a higher quality
fedora domain page, which includes a link to the red hat page.

=== decause notes ===

dsilas - Content Services Management Overview
When I started the Doc Services Program Manager Role, I wanted to piece
together the toolling situation across products and teams. it is quite
complicated. That is what this spreadsheet is.

This column "What formats are the product docs in?" we've used docbook for many
years. We have some asciidoc, but I'll talk about that shortly. When I talk
about toolchain arch, whenever we have markdown, we'll have to convert.

Q: Between asciidoc and markdown?
A: Markdown is meant to be simple, there isn't much tooling inside of it. The
original implementation had some flaws (markdown.) asciidoc has more semantic
information than markdown.


dsilas: When I'm talking about asciidoc, it's actually asciidoctor (the fork.)
The transformation is pretty much across the board. It's not only content
services, but most of our upstreams too. One of the directors in middleware, he
decided to take his orgs (BRMS, BPMS) are going to asciidoctor too.
Standardization can be a real challenge in RHT sometimes.

OpenShift upstream gets lots of contributions for instance by keeping a standard.

==Tools Demos ==

Anerist - immanetize
Pantheon - dsilas
Taskotron - Pete
pintail - smccance
jenkinscat - dsilas



== Tools Review ==

https://ethercalc.org/txnb0f8lewsz


== Personal Reflections ==

Zach Oglesby (Baltimore MD, Fedora docs team member)
day1
day2
day3

Shaun McCance (Cincinnati, Red Hat community docs)
day1
day2
day3

Stephen Gilson (Westford, Red Hat product docs)
day1
day2
day3

Paul Frields (Fredericksburg VA, Red Hat Fedora eng)
day1
day2
day3

Ryan Lerch (Brisbane QLD Australia, Red Hat Fedora eng)
=======================================================

day1 - we dicussed the high-level potential goals for a new docs angle, and
tools. I was primarily focussed in these discussions on making the new tool
options and content plan to enable new users to easily and quickly contribute.

day2 - day two, we started with presentations about potential tools. Primarily,
these wwere focused on tools that take static input files, process them via
some sort of CI tool, and then output static html. The other style of approach
is a wiki/cms esque solution that users could write and submit artilces for
display on the docs site, and a editor could easily edit them and push them
live all via a web interface, without reliance on commandline tools, users
interacting with git repos, etc. 

My concerns with the Static input>GIT>CI>static output approach is that it
potentially makes it harder to make the contributons portion of the site easily
usable by new contributors. As well as the potential issues that might arise
from having a bunch of text files with stored metadata in and problems that may
occur when trying to edit or manipulate this metadata at scale (with over >1000
srticles.) One item that i think we all universially agreed on was to use a
single source format, and for it to be a markdown/rst/asciidocesque style
format over a heavy semantic markup like docbook. This is a plus for enabling
new contrinutors in my book (hardly any possible breakage of docs because of
mistagged anything, it might be noy super readbaly, but it will "build"). 


Silas Hensley (Brno, Red Hat product docs)
day1
----
It was really interesting to see how Paul Frields would organize the project to
bring together disparate parties representing somewhat differing agendas and
ideas to come to a more-or-less unanimous decision on what needs to be done to
get the Fedora documentation site and project back in better working order and
to establish a set of agreed-upon format and tool decisions. Paul mentioned at
a later point that we were actually able to come to an agreement more quickly
and easily than he at first prognosticated. So the primary task of the first
day was to come up with a list (we ended up with ten) of who the Fedora
documentation project's contributors are expected to be, which certainly
includes Red Hat Content Services members who have some (albeit limited)
capacity to work upstream, as well as New Contributors, Experienced
Contributors, Publishers (Pete), simple readers, SMEs, Content Strategists,
Tools Maintainers, Translators and others. With these profiles established,
post-its were passed out and each FAD attendee wrote down as many use cases for
the Fedora documentation as we could think of. Once done, categorized all of
the use cases by contributor persona. All of this would ultimately (2nd day)
represent the criteria by which we'd evaluate the toolchain decision. I think
everyone considered this an excellent way to drive toward consensus on the
decisions we'd make while reducing the possibility of us overlooking any
important use cases.

day2
----
Day 2 was the big format-and-toolchain showdown, and there was lots of
passionate discussion. We discussed competing formats such as Mallard
(represented by Shaun McCance, naturally), AsciiDoc, markdown and DocBook
(quickly rejected by all as too heavyweight and the desire to move away from
Publican-built site generation). For the format discussion, Stephen and I
represented the Content Services team, particularly the Platform team in Brno
who have traditionally been pretty heavy-engaged Fedora docs contributors. It's
recognized by all that the ability to easily upstream and downstream
documentation between Fedora and RHEL—at the intersection of where it makes
sense for and is benefical to both—is desirable to all parties, and I made the
case that reducing the impedance mismatch as much as possible would go a long
way toward enabling more Fedora docs contributions (mentoring, etc.). I
presented first in the morning, and began my talk by showing the clear format
trend from my Tooling Survey across Content Services, including a vast number
of product upstreams, away from DocBook and toward AsciiDoc. I then discussed
how are build toolchain is implemented and concentrated on the workflow and
build system architecture. I showed Lee Newson's recently-revised Docs2Drupal
publication architecture diagram and discussed Jenkins, Pantheon and the
emender testing framework. Components such as Pantheon and the underlying
ccutil utility haven't been licensed or open sourced, but I discussed the fact
that they could be. Once the tooling discussion moved on though, it was
apparent that the need to devise a working solution quickly that was simpler
than whan Red Hat currently uses to build all of our documentation was called
for. That said, I did discuss emender-as-a-service and we discussed ways that
the Fedora documentation project could use it. 

By the end of the day, we had come up with several tooling alternatives and
applied all of the important use cases to each of them, Remy patiently doing
the bookkeeping on the degree to which each solution addressed the use case (or
failed to), and at the end of the day, the AsciiDoc-Pagure-Pintail had won out
over the other contenders, which included a number of wikis, such as MediaWiki,
Drupal and Kuma. I was happy with this resolution both because I believe the
architecture is sound and will be effective, but also because a Git-based
solution—especially in AsciiDoc—makes upstreaming and downstreaming simple, if
not quite trivial.

Day3
----
I showed off emender a bit more, looking at the System Administrator's Guide,
and discussed with Pete how to help enable them to accomplish any toolchain
issues that might come up, and discussed with Shaun the possibility of
supporting Mallard in Content Services. Overall and to sum up, I thought this
FAD (my first) was extremely well-run, effective, and that we made a lot of
progress on fixing what was almost an intractable issue. I'd like to thank Remy
and Paul in particular for organizing and running this FAD, and felt honored to
be able to bring the knowledge and support from Red Hat development teams, and
the Customer Platform development team under Erik Newby in particular. I do
believe that my attendance will have benefits outside of the immediate impact
for the Fedora Docs Project, and I'm looking forward, for example, to putting
Pete in contact with Tomas Capek, the Documentation Program Manager for all
Platform documentation. Kudos to all involved!


Remy DeCausemaker (Raleigh, Red Hat OSAS/Fedora community lead)
day1
day2
day3

Jim Perrin (Houston Tx, CentOS Project)
day1
day2
day3

Pete Travis (Fedora Docs)
====================
Day1
-------
Friday saw rapidly moving and well organized discussion, thanks to the
direction provided by Paul.  We outlined ten distinct personas representing the
marjority of contributors to Docs, then whiteboarded many user stories for each
persona.  This was a huge boon for our focus; the use cases for each persona
was considered in future discussions, both in terms of tooling and
participation workflow.  Upstream and downstream collaboration on content
production was given a high priority. The use cases were then prioritized for
later comparison with potential publishing stacks.  

Day2
-------
The established requirements from user stories were crucial to our
consideration of publishing tools.   We outlined six potential stacks after a
brief review of related solutions and projects, and assessed each in terms of
technical viability, reader ease of use, and contributor workflow.
Categorically, two options were compared to the requirements: CMS based
solutions with browser input and dynamic rendering, and static site generated
from plain text markup in git repos.  While the CMS based solutions won out
over static site generation for ease of contribution by casual or non-technical
contributors, we found that the workflow and benefits of the plain text markup
approach met far more of our priority requirements.  A brief and sprited
discussion of implementation details followed, and the day ended with a clear
goal to explore an implementation using pintail to consume content from
repositories hosted on pagure, with the output going to the existing Fedora web
proxy infrastructure.

Day3
-------
All implementation planning here.  We discussed what the end site would look
like, identified action items to carry away from the meeting, and began some of
the preparatory work.  Many of these are listed at
https://pagure.io/docs-fp-o/issues; some were filed with their respective
upstream projects.