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 http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://redhat.com/ - - - - http://pfrields.fedorapeople.org/ The open source story continues to grow: http://opensource.com -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
