On Feb 4, 2016 12:15, "Pete Travis" <me@xxxxxxxxxxxxxx> wrote:
>
>
> On Feb 4, 2016 10:26, "Paul W. Frields" <stickster@xxxxxxxxx> wrote:
> >
> > On Thu, Feb 04, 2016 at 08:20:27AM -0500, John J. McDonough wrote:
> > > On Thu, 2016-02-04 at 11:54 +0100, Paul W. Frields wrote:
> > > > Short articles and wiki pages and other similar focused docs, on the
> > > > other hand, have really eaten our lunch, as far as being the places
> > > > users go to find information. I routinely run into users who tell me
> > > > they find answers for how to do things for Fedora on StackExchange,
> > > > Arch wiki, Ubuntu forums, and so forth.
> > >
> > > 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.
> >
> > (1) The Docs team efforts haven't really gone to short articles, but
> > rather to long works that are even harder to deal with, not to mention
> > off-putting to new contributors (whose long tail is supposed to be the
> > focus of growing a community, or subcommunity like Docs).
> >
> > (2) The wiki is not somewhere we want to send users, so it's not
> > relevant to my topic -- even though you are exactly right about
> > it. :-)
> >
> > > With a small number of documentation products, it is a lot easier to
> > > keep track of the documents and identify them as to the version they
> > > reflect.
> >
> > This is true when you constrain yourself to the toolset now in use.
> > But I contend it can be done more easily with more, smaller docs with
> > different tools.
> >
> > > It makes me wonder whether some of the web-based git tools might help
> > > (OK, I'm a major git fanboy). Most of the public git repositories
> > > include a wiki. If we could somehow tie that wiki to branches or even
> > > tags, perhaps we could develop a more edible set of documents that
> > > would allow the user to find not only the information needed, but also
> > > for the appropriate period in history.
> >
> > You're on the right track with git management here. Git solutions on
> > the web already allow inline editing by anyone. They can submit a
> > pull request without being anyone "special" in a given project.
> >
> > Drive-by contributions are perfect for docs (and really they're the
> > lifeblood all open source projects would love to have). I contend we
> > should optimize for that, because all other contributors' lives get
> > easier as a result -- riding the wave.
> >
> > I am also contending that the Docs team should not be developing a
> > solution on its own. There are too many tools out there already
> > waiting to be used for this purpose. Instead, identify some best of
> > breed tools that fit together for this purpose.
> >
> >
> > --
> > Paul W. Frields
>
> You've quite effectively recapped the conversations we've been having for a year or two now :)
>
> The core issue *is* the tooling; with some well defined constraints:
> - Infra wants static content
> - writers want their preferred markup
> - the current platform doesn't meet those needs or address the other issues you mentioned
> - We really like using a git based workflow
>
> I didn't find a thing that met those needs, so I've been trying to write one that can use existing html renderers, throw a menu on top, and handle the publishing process in an event-driven CICD type way so those drive-by contributions are easy, and writers can focus on writing. Is roll-your-own the best approach? Maybe not; it might be better to buy into one specific markup and find a platform that meets the other needs.
>
> Frankly, this needs an FTE for a while, regardless of the direction we take, or the conversation will keep repeating until volunteers scrounge enough time to fix it.
>
> --Pete
Oh, and I am vaguely familiar with the specific CICD docs platform addressed in the opensource.com article you referenced; some of the technical writers that work with it are just down the hall, literally, and one of the meetups David and I attended gave a decent overview of it. It's an entire scale-out cloud application stack with a handful of dedicated sysadmins to mind it, built on http://deconst.horse and some more. There would be a lot of packaging, debundling, and deployment work to use it. I heard rumblings recently that the solution is changing; not enough to really speak on the changes, but enough that my internal team's public writing ventures are on hold until it settles down.
--Pete
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
