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.
- We really like using a git based workflow
- 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 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@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
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
