So this makes me think of a question about guides.
If someone or a group make a guide that pertains to a version of Fedora,
it becomes their responsibility to update and change it for future
releases unless someone offers, gives assistance, or updates it on their
own accord?
Is that a problem we have currently, when authors stop updating their
guides for whatever reason?
Thank you,
-Glen
On 07/13/2015 05:57 AM, Brian (bex) Exelbierd wrote:
Hi Sandra,
I was traveling and took some time to get back to this.
> On Jun 25, 2015, at 4:37 PM, Sandra McCann <scmccann2000(a)gmail.com
> <mailto:scmccann2000@gmail.com>> wrote:
>
> The first question that comes to mind is how do these individual
> articles combine/link into a cohesive whole? While I'm not in love
> with the book paradigm, it does take care of that logical grouping
> and flow from one topic/article to another.
There is a lot packed into this statement. I agree that a "book
paradigm" creates ordering and topic curation. A big fear of mine,
and it seems of yours, is that anything that is "article" based
becomes a kitchen utility drawer of disorder and chaos. The knife you
want it always at the bottom and you know own 42 differently sized
grapefruit spoons because you either forget you have one or you can
never find them.
I think that the key is that we can still have order and curation, but
we need to think about writing our topics in a more independent way.
This is not a new thought and I am far from the first person to state
it here. Perhaps what is needed is an assessment of what that really
means and a through review and modification of one group of topics
(aka book) to get it there and see if it works.
> And how do these articles handle release to release variations, or
> will some background magic pull them into an F23 specific section or
> an F22 specific section etc.
The goal, as I understand it, is to have F22 material and F23
materials, for example, separated. If something "rolls forward"
unmodified, let's have two copies. git is pretty efficient so I am
not worried about disk space.
> I guess my worries are from the end user perspective. How will I know
> what I can do with astronomy and Fedora, and be sure I've found all
> the content vs select articles?
Tagging can help here. My response would be that the Astronomy SIG
should be doing two things: 1) Building a curated index/TOC of topics
for their materials and the related bits. 2) Adding specific topics
that are for their SIG.
regards,
bex
>
> Sandra
>
> On Mon, Jun 22, 2015 at 10:21 AM, Brian (bex) Exelbierd
> <bex(a)pobox.com <mailto:bex@pobox.com>> wrote:
>
> I talked with randomuser about strategy moving forward. I have
> written up our conversation in an interview style. The primary
> goal is to start some conversation around these topics. Therefore:
>
> YOUR HOMEWORK: Send an email back with the questions this raised
> for you
>
> Our ulterior motive is to further inform our presentation at Flock.
>
> ---
>
> To understand where we are going, we have to know where that is.
>
> *What is the goal of the docs group and docs.fedoraproject.org?*
> <
http://docs.fedoraproject.org/?*>
>
> The docs group as having two basic, related goals: assisting
> developers, and assisting users. Our current strategy does a
> reasonably thorough job of assisting users, but we don't do as
> well with assisting developers, or new docs contributors, for
> that matter. There's lots of new crazy code out there, and the
> large book strategy has a lot of inertia and can feel stifling
> when it comes to new additions and rapidly changing areas.
>
> *How do we fix this?*
>
> The high-level solution is to enable developers and experienced
> users to write about whatever they like to do. We would use a
> workflow that leverages the Docs Team's greatest strength,
> experience. People can work with seasoned writers to produce very
> high-quality work.
>
> The biggest problem Docs contributors have is finding something
> to do, so that workflow should provide a pipeline of requests
> working through clearly defined steps. a request could be from a
> user ie
https://bugzilla.redhat.com/show_bug.cgi?id=1229560 or
> from a developer, ie the API reference discussion, or internally
> generated by the docs team as a need for an upcoming release.
> The focus of this process should be on the quality of content and
> the efficacy of addressing a specifically defined topic. Someone
> shouldn't have to worry too much about markup or tools unless
> they've specifically opted to work in a markup or with the tools.
>
> This goes beyond just telling people, "You can write whatever you
> want however you want and get help with the publishing." That's
> not enough. The scope of our books is really too big to
> facilitate focused topical writing. The cookbook is evidence of
> that; Randomuser has offered cookbook assistance to many people
> and few take the bait. The new strategy is to build
> publishing/site generation tooling that supports varied content.
> This way contributors can range from independently capable
> writers, to SMEs looking to share but not learn the specifics of
> publishing, to requesters, to those wanting to write but needing
> assistance to get there.
>
> Ideally, we reach a point where each specialty group/SIG has a
> set of articles covering their interests, in a format that
> they're able to maintain. The only real example of that we have
> is the Amateur Radio Guide. And this is is basically
> single-handedly maintained by jjmcd, despite there being many
> other Fedora contributors doing radio stuff. This isn't ideal,
> but it is working for today. Rather than try to fix a working
> process, let's try to get more folks on-board, for example the
> Astronomy SIG.
>
> *How are we going to implement the solution?*
>
> Implementation is a challenge. There are two aspects,
> **Community** and **Tooling**.
>
> On the community side, We don't have a well conceived plan (other
> than sharing and organic growth - which is slow and not
> guaranteed). This is critical as tools are not valuable if no
> one uses them. We can't grow our docs if maintenance consumes
> all of the folks involved.
>
> With regards to tooling, we have lots of bright people and lots
> of ideas around tooling. Tooling is solvable and being worked
> on. You can contribute to and follow the progress at
>
https://github.com/immanetize/anerist . But beforewarned, it
> could be be better described.
>
> *How do you envision the workflow for a new content change/addition?*
>
> The system consists of a bunch of restricted commit repos
> containing large guides, collections of ReST articles, whatever.
> When a change is committed to a repo the tooling will see the
> commit and attempt to generate html from the affected files. If
> that succeeds, (and hopefully if it passes some validation tests,
> the strings in Zanata (Internationalization Tool) will be
> automatically updated to make the work available for translation
> immediately. The tooling will also extract some metadata from
> the document (title, subtitle, abstract, categorical information,
> etc.) and ultimately use that to generate a stage version of the
> docs site for verification before publication.
>
> An individual contribution comes in via a pull request workflow.
> This could be via a pagure.io <
http://pagure.io/> solution or via
> a traditional git clone solution. Pagure.io has the benefit of
> bringing the fork/edit/PR process into a web-based format perfect
> for many contributors and for drive-by contributors. The merge
> starts the process just mentioned.
>
> Ideally we can support acls on a per branch and repository
> basis. This way a SIG, for example, could have control of their
> specific documentation by merging PRs. Members of the
> docs-writers group would have global commit capability. The
> branch structure can resemble many popular open source projects
> with a master that is clean and release branches for future
> maintenance. The system is branch-aware, so everything from
> 'master' goes to a draft area, things in f$n gets labeled as
> appropriate for f$n.
>
> *What are our big blockers today?*
>
> 1. Community Outreach and Growth Plan.
> 2. Website redesign for
docs.fedoraproject.org
> <
http://docs.fedoraproject.org/> - it is stalled on some
> decisions around older docs, etc.
> 3. Publishing is stalled on both design and the need to integrate
> legacy tools such as publican in a new paradigm with other
> formats that use other tools. These need to all roll to a common
> docs listing/Table of Contents.
>
> --
> docs mailing list
> docs(a)lists.fedoraproject.org <mailto:docs@lists.fedoraproject.org>
> To unsubscribe:
>
https://admin.fedoraproject.org/mailman/listinfo/docs
>
>
> --
> docs mailing list
> docs(a)lists.fedoraproject.org <mailto:docs@lists.fedoraproject.org>
> To unsubscribe:
>
https://admin.fedoraproject.org/mailman/listinfo/docs