On Thu, Feb 04, 2016 at 09:50:59PM -0600, Pete Travis wrote: > On 02/04/2016 03:00 PM, Dylan Combs wrote: > > *- writers want their preferred markup* > > > > What writers are actually demanding particular markup support? Do we have > > a list of demands? I have no idea what kind of person would be like "Well > > if it's not XML, I'm not writing it!" but maybe they exist. Is this really > > a significant obstacle? I'd settle for documentation written in good old > > fashioned UNIX-style plaintext, myself. The markup support seems like a > > tertiary concern to me. I'd value easily modified, up-to-date plaintext > > documentation way above difficult-to-modify, outdated documentation that > > has to go through an elaborate build process so that it can be delivered in > > a variety of pretty formats. > > I haven't come across any outright demands, but whenever the > conversation comes up, people do voice preferences. > > We have an active group of content engineering folks that are able to > leverage Fedora Docs as the 'upstream' for their work on Red Hat docs, > and I am concerned about making contribution less appealing for them by > requiring a departure from the markup they use 'downstream'. How would it affect this discussion if we were able to get some of the Red Hat content folks on board with both of: (1) the model of smaller, more modular docs; (2) tooling that worked like a git/pull-request model? I ask because I'm located near some of these guys this weekend and part of next week. It's a good opportunity to see if we can build some project work around this idea, and break the cycle of "we're stuck because this is really hard and takes time" -- which is ABSOLUTELY VALID, and a problem I'm familiar with from previous lives. ;-) > There are developers and content creators in the community already > conversant in markdown, restructuredtext, asciidoc, whatever. > Supporting formats that people already know and use makes participation > easier for them, and offers the opportunity to reuse existing content. > A plaintext site would lead to a diaspora of bespoke formatting > conventions, and the ultimate result would either be awkwardly > inconsistent, or the emergence of a new markup standard. Neither appeal > to me. > > I've heard "I don't want to write in DocBook, but I would write in > $this" for at least seven values of $this. Often enough that choosing a > different only and mandatory markup language is not appealing. While having a preferred standard is helpful for people who don't know any, I agree that a modular approach is helpful, as long as you can transform to the preferred format. > > *- the current platform doesn't meet those needs or address the other > > issues you mentioned* > > > > I think Paul is focused on the right points: our primary concern should be > > providing a documentation platform which makes it incredibly easy to locate > > the right information and submit drive-by contributions. We can all > > benefit from such a solution, and that's the way to make sure documentation > > gets maintained. > > I don't disagree with Paul's observations, and have said most all of it > myself. It should be easy to contribute to Docs, it should not be a > burden to contribute an article or an edit to an article, casual > participants should not have to worry about the publishing > infrastructure. Making that happen for a distributed group of > participants with varied levels of engagement working on a large, > diverse body of content that will be globally distributed at scale is > less simple; you must offload the complexity into the platform in order > for users of the platform to experience that ease. In short: The tools should do the work, not the people. Spot on. And as Pete said, nothing I brought up was really novel. I was moved to reiterate after leafing through some of the current docs.fp.o. As I mentioned above, I'm really interested in getting some content services folks involved in the conversation. But I feel that should happen because Pete and other Docs folks *want* it to happen, not because I happen to be near them this week. So I guess my question a few paragraphs back still holds: if we can get some resources for this (IOW, people/time/passion), would joint work be of interest? -- 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
