On Thu, Aug 11, 2016, at 09:34 AM, Brian Exelbierd wrote:
This email is to drive some discussion around $subject. It
follows from
a blog soon to be posted on the Fedora Community blog
(
https://communityblog.fedoraproject.org). The text below is copied
from that blog:
How do we move to topic-based writing? Is there a plan?
After the FAD there was not a finalized plan, but planning
began during
this session. Many ideas were mentioned and consensus seemed to form
around just writing new topic material. Folks from the Gnome project
pointed out several reasons, including efficiency, for why they
rewrote
their materials when shifting from books to topics. Another benefit of
starting from scratch is that new material can be written in a
priority
order possibly based on search keywords.
One challenge here is that right now we have no place to put
and publish
these new topics. It was quickly pointed out that this is the "tools
problem" and it has many solutions. Instead of letting tools be a
blocker however, it was proposed to have people just write.
"Write it in
any format, any markup, any program, even on paper and just send it to
us. We will get it published." This turned into a discussion of
how many
topics are also good for the Fedora Magazine. So the suggestion
was made
for folks to consider submitting material there first and we
can pull it
back into docs later. Additionally folks can email the docs
mailing list
or me. I am super excited to tell you I got an email with a topic 35
minutes after the session ended
Please reply here for discussion.
regards,
bex
I will be the first person to admit that I have not put much thought
into this topic, as I have been more focused on getting the new website
up and running.
One topic that we did touch on at the FAD was the idea of "write it
however you want and we will do the work to get it published". I will
summarize that on two levels, the first was the idea that we could
support many as markup languages as possible on the site to allow people
to write documentation in whatever they are comfortable with. We
ultimately suggested that this approach not be taken as it will require
a lot of effort in tooling, and as I discussed in my blog post on the
FAD, most markup languages are not really meant for documentation they
are easy ways to write text that can be displayed as HTLM as such we
don't get a lot of the semantics that we get with DocBook or asciidoc.
The second is the give docs what you have and we will make asciidoc out
of it for you. This is great on paper but can quickly fall apart once it
is put into practice. Say a user provides us with a topic in another
format and no one touches it for months, that user is going to become
disenchanted and will most likely not contribute again. In order to
avoid this kind of issue I would say it would be better that as a policy
we only take properly formatted documentation, but if a member of the
docs team talks is willing to take ownership of a pull request upfront
to convert it, it can be accepted. This way users are not doing work
that sits on the table for months without hearing anything (it will
happen), and we know that in situations that we do accept that work
someone is on the hook to do something with it.
As for a location to put this work in the short term. I think the best
way of dealing with it for now is using the cookbook repo[1], as that
was its original workflow. We still have to workout the final
organization of content for the topical documentation, but I think that
at least in the short term, keeping it all in one location will allow us
to identify everything new we already have going forward.
[1]:https://pagure.io/fedora-cookbook