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.
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
