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.
*- 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.
*- 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.
*- 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.
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
On Thu, Feb 4, 2016 at 3:03 PM, Bryan Sutherland <bryan.sutherland(a)gmail.com
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
--
docs mailing list
docs(a)lists.fedoraproject.org
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@lists.fedoraproject.org