Re: Fedora Publishing

[Dylan Combs <dylan.combs@xxxxxxxxx>]

I am little beyond a long-term lurker around here, but at the risk of being immediately (and possibly rightly) despised, I will say that a big part of the reason for that is my reluctance to even attempt to figure out how to submit documentation changes or additions.  Despite lurking for a while, I still know embarrassingly little about how our documentation is created or even what the high-level architecture is for our documentation; for some reason we have some sort of build process beyond simply modifying content in a text-based editor and clicking a button and I don't know why.  Maybe figuring that out would only take an hour of my time, or maybe it requires some sort of relationship with other Docs members so that I can be mentored or who-knows-what, but the fact that this is harder than something anyone can immediately figure out in two seconds on the Internet is enough to dissuade me from bothering.  It's much easier to write guides as I determine the information is needed and post them to my blog; the administrative overhead I incur during those operations is nearly non-existent.  I simply write text, click a button, and am done.

Now, I may be so n00blar that I have an inadequate understanding of the reasons behind the Fedora Docs infrastructure design choices, but when I first envisioned participating in the Docs group, I expected a mega-simple process in which I simply use a browser to navigate to the content in need of updating or correcting, make the addition or correction, and press a button to trigger the pull request.  I was further hoping it'd all be heavily integrated with man pages, but that appears not to be the case.  In my documentation dream world, I am simply permitted to submit pull requests for man page modifications for any Fedora package from one streamlined interface, but that appears not to be something we do.

Why our solution is not that simple, I do not know.  Is it really merely that we're afraid of poorly maintained Wiki articles?  If so, some sort of aging indicator that pushes stale content to the top of a "To Do" list or something seems like a good way to keep maintenance focused.  Rather than trying to decide on a short-form or long-form format into which we will cram documentation, can we not simply permit everything to be a bit more amorphous, lengthening and shortening as the needs of the community demand?  I was expecting something like Arch Linux's renowned ArchWiki documentation system, for example.  If such a system could be integrated intelligently with relevant man pages (even just links to relevant GitHub content would be a nice way to funnel interested parties to other packages' documentation so that it can be maintained as well), such a solution would be near-perfect, in my eyes.

Wouldn't it be nice if it were that simple?  It'd be nice if everyone on the Internet could easily and quickly submit documentation which simply awaits the judgment and subsequent rejection or integration by community-elected moderators (e.g. members of this group, or what-have-you). 

Maybe I'm overlooking obvious complexities, but I don't know what they are. Why don't we simply pursue a flexible, easy-to-use ArchWiki-esque solution and focus on streamlining maintenance to address concerns in that field?  As has been observed above, such Wiki-based systems are those which are preferred by end users, and for obvious and good reason, if you ask me.  I say we give the people what they want and thereby open the field of contributors to anyone who should pass by the Wiki site, which should also make the lives of maintainers easier in the process, right?

My apologies for any time wasted on account of my ignorance.

-Dylan

On Thu, Feb 4, 2016 at 8:28 AM, Matthew Miller <mattdm@xxxxxxxxxxxxxxxxx> wrote:

On Thu, Feb 04, 2016 at 08:20:27AM -0500, John J. McDonough wrote:
> The challenge with short articles is maintenance.  Google anything on
> Fedora or Linux for that matter, and almost everything will be sadly
> out of date or just plain incorrect.  That even applies to our own
> wiki, in spite of numerous attempts at wiki gardening.

I've said this before, but I will buy a case of $PREFERRED_BEVERAGE for
whoever implements pirate-mode aging a la Trello
(http://help.trello.com/article/820-card-aging) for any new docs
solution.

And another for anyone who does it for the wiki.


--
Matthew Miller
<mattdm@xxxxxxxxxxxxxxxxx>
Fedora Project Leader

--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx

--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx