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