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.
