On 02/04/2016 03:00 PM, Dylan Combs wrote: > In the interest of not letting this rehash of a year-long conversation die > (like the last one, apparently?), could you explain more about the > following items, Pete? I've put your text in bold and my questions in > plaintext. If I'm going about this all wrong, let me know, but from where > I stand, I can't help but think this isn't as difficult as it's being made > out to be. > > *- Infra wants static content* > > I don't know what "Infra" is (the...Infra...structure...team?) or what is > meant by "static content." Do you mean some group of stakeholders wants > manuals which can be published in a permanent format so that it does not > change until the new version or whatever? If so, meeting that demand > alongside more dynamic, progressive content seems fairly easy as long as > whatever solution we go with has the ability to simply snapshot > documentation and compile it for presentation and archival, but this seems > like it ought to be a very secondary concern beneath up-to-date, accurate, > well-maintained documentation. End users just need to be directed to the > correct documentation, and with a well-moderated dynamic content model, the > most recent stuff should be the correct stuff. We could have snapshots of > the content as it was at the time of release for previous Fedora versions > or something for posterity, but aside from that, it seems the primary > concern is keeping documentation fresh and accurate. Infra, as in the Fedora Infrastructure team that would provide the resources required to run shared tools and public websites. Dynamically generated content typically uses server-side code and a database backend to generate webpage content, whereas static content is prerendered html files that do not require server side processing. The maintenance burden on infrastructure and sysadmins for distributing flat files is dramatically lower than the investment required for a web application, especially at scale. Regenerating a webpage when the content changes requires far less resources than regenerating the webpage every time it is requested by a visitor to the site. Your observations are equally valid for both dynamic and static content distribution models. > *- 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'. 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. > *- 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. > *- We really like using a git based workflow* > > Maybe some elaboration could help? I mean, I like Git, too, but it might > be overkill for this matter? > > As I said before, I don't see why we don't just use an ArchWiki-style > solution. Of the above points, I guess 1 and 2 might be against it, but I > don't really understand them yet. Other than that, it seems a simple Wiki > is enough to solve our major problems here, no? GitBook seems cool, too. I have personal complaints about wikis, but setting those aside, the Fedora Project does not have a strong wiki gardening culture. The state of the current wiki would be the fate of another wiki, because the people we want to participate already deal with wikis that way. The static vs dynamic content argument applies, and to a lesser extent, so does the markup argument. > It seems like we're stuck in a morass where we're crippling ourselves by > trying to fully satisfy a large spectrum of concerns as though they're all > equal. My guess is that we can trim away the less critical stuff (like > support for a variety of markup languages or the delivery of static content > in a variety of formats) and dramatically simplify the solution with a > focus on getting content flowing more freely and consistently. > > -Dylan I'm willing to give up on a variety of output formats, but that doesn't seem to be an especially challenging part of the puzzle. Presenting the content in an organized and structured way, without adding a ton of work to maintain the organization and structure of the content, is. We don't need to support a variety of markup formats out of the box, but the *potential* to support more than one format is IMO a requirement. The morass is real, and so are the problems that need to be solved to get out of it. You're welcome to help find a solution, we'd all be exited to find something that meets whatever needs the group can agree on. If you're interested in some historical context, https://lists.fedoraproject.org/pipermail/docs/2015-February/016015.html and replies would be a good place to start. > > On Thu, Feb 4, 2016 at 3:03 PM, Bryan Sutherland <bryan.sutherland@xxxxxxxxx >> wrote: > >> Have you taken a look at the GitBook ( >> https://github.com/GitbookIO/gitbook and https://www.gitbook.com/). It's >> a node application that builds books/documentation from Markdown/ASCIIDoc >> files. >> >> Just a thought... >> >> Bryan >> I hadn't, will read up on that next. I've been looking at hugo, https://gohugo.io , this evening; it could be an interesting fit. I do think it would be valuable in the long run to avoid getting tied to a particular format (or at least consider that when evaluating options) and hugo has a modular architecture to plug in external helpers for various input formats. -- Pete -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
