19:28:06 <randomuser> #startmeeting Fedora Docs Office Hours
19:28:06 <zodbot> Meeting started Thu Jan 22 19:28:06 2015 UTC.  The chair is randomuser. Information about MeetBot at http://wiki.debian.org/MeetBot.
19:28:06 <zodbot> Useful Commands: #action #agreed #halp #info #idea #link #topic.
19:28:16 <randomuser> #chair zoglesby pbokoc jsmith Sparks
19:28:16 <zodbot> Current chairs: Sparks jsmith pbokoc randomuser zoglesby
19:28:30 <jsmith> .hellomynameis jsmith
19:28:32 <zodbot> jsmith: jsmith 'Jared Smith' <jsmith.fedora@gmail.com>
19:28:38 <jsmith> Greetings, all!
19:29:17 <randomuser> hello jsmith
19:29:19 <pbokoc> https://38.media.tumblr.com/f6b924a87fda14269caa942e9098472a/tumblr_mk64uduWaj1s2ph3mo1_500.gif
19:29:32 * randomuser is currently dealing with a fun batch file problem
19:29:45 <randomuser> where 'fun' == 'would you just die already'
19:31:14 <pbokoc> I sense anger in you, that can't be good for your chi
19:31:46 <randomuser> yes, you're right
19:32:38 <randomuser> I should see this as an interesting new challenge rather than a terrible old problem
19:36:09 <pbokoc> that's the spirit!
19:36:18 <pbokoc> become a zen master and annoy everyone with your inner peace :))
19:37:31 <randomuser> zen masters do not embrace futility
19:39:57 <pbokoc> I think they do... that thing with the sand garden or whatever
19:40:33 <pbokoc> anyway, randomuser, do you know what timezone Ben Cotton is in? He said he wanted to contribute to the install guide and I want to talk to him a bit to make sure we're on the same page
19:40:46 <pbokoc> but I'm not sure if I can catch him on IRC
19:41:24 <jsmith> So, Sparks got me thinking...
19:41:39 <jsmith> Hear me out for a second, because this is going to be a radical idea...
19:42:07 <jsmith> ... What if we decide it's time to abandon DocBook altogether, and move to MarkDown
19:42:14 <pbokoc> no, we're not abolishing the government :))
19:42:20 <jsmith> So that anyone can write docs in a web gui
19:42:25 <pbokoc> jhradilek, ^
19:42:31 <jsmith> and instantly check it into git
19:42:46 <jsmith> And because we're not using XML, there's no validation to worry about
19:42:52 <jhradilek> Please, please, please, not Markdown.
19:42:56 <pbokoc> jsmith, we've been kinda talking about something similar, somewhere. I'm not sure Markdown is the right choice though
19:43:02 <jsmith> And it's almost as easy as a Wiki...
19:43:16 <randomuser> jhradilek, RST ?
19:43:19 <jsmith> ... (or perhaps easier, if you prefer MarkDown to whatever wiki syntax you hate)
19:43:21 <jhradilek> I spent a non-trivial amount of time investigating various lightweight markup languages and Markdown is a terrible, terrible choice for documentation.
19:43:41 <jsmith> jhradilek: I 100% agree -- but I'm just throwing it out there for discussion
19:43:43 * randomuser gives up, is getting lunch
19:43:49 <jsmith> randomuser: There's the spirit!
19:44:14 <randomuser> it's getting interesting in here, but i have to eat before an afternoon meeting :(
19:44:18 <jhradilek> It was designed to help web developers, but not as a complete replacement of HTML. As a consequence, it relies on HTML quite a lot when it comes to advanced formatting like tables, nested itemized lists, code blocks, etc.
19:44:23 <jsmith> ... and here's the second half of my proposal ...
19:44:45 <jsmith> That what I've proposed is just *phase one* of a two-phased approach
19:44:53 * jhradilek shuts up.
19:45:43 <jsmith> Then for phase two, geeks like us take that and mark it up in DocBook/Mallard/whatever
19:45:57 <jhradilek> jsmith: I like the ability to choice.
19:45:59 <jsmith> and turn it into something more ... structured (for lack of a better word)
19:46:06 <jsmith> That way, it's easy for folks to get started --
19:46:12 <jsmith> -- there's a beginner tier, and an advanced tier
19:46:17 <jsmith> Sparks: What say ye?
19:47:12 <pbokoc> well, if it worked like that, we could allow people to send their contributions in pretty much any format, even plaintext, or a word doc
19:47:23 <pbokoc> I mean, I'd be fine with that now, marking it up is fairly easy
19:47:40 <pbokoc> we just don't make this obvious anywhere so people probably assume they MUST learn DocBook to contribute
19:47:48 <jhradilek> jsmith: But I would argue that AsciiDoc would be a better choice; it is not more difficult to learn than Markdown, it is "standardized" (unlike Markdown where every implementation uses its own dialect), and it is designed for both articles and books (and thus supports admonitions, tables, abstract, code blocks, etc.)
19:47:48 <jsmith> We already do -- we just don't advertise it enough
19:48:05 <pbokoc> yeah
19:48:21 <jsmith> jhradilek: Yeah, that's fine ... I just find that asciidoc requires a lot more work for a newbie to learn
19:48:37 <jsmith> jhradilek: Plus, there are a lot of people using markdown with github already...
19:48:54 <jsmith> jhradilek: Again, my proposal isn't about picking the *best* tool
19:48:59 <jhradilek> jsmith: So does Markdown if you want to use all of it, most people just use what the page suggests.
19:49:11 <jsmith> jhradilek: It's really just running with an earlier comment from Sparks about picking the "most simple" tool
19:50:13 <Sparks> jsmith: No, see, I was too busy watching TableTop.
19:50:44 <jsmith> *le sigh*
19:52:25 <Sparks> jsmith: So I've started using a program called pandoc to convert from DocBookXML to ASCIIdoc and it seems to work pretty well.
19:52:35 <jsmith> Sparks: https://github.com/oreillymedia/docbook2asciidoc
19:52:47 <Sparks> I suspect that there wouldn't be too much trouble to go the other way if necessary.
19:53:12 <Sparks> And maybe we could add support to Publican for ASCIIdoc (or whatever the format desired is).
19:53:26 <randomuser> I've been using pandoc to create docx files, it's nice
19:54:04 <jsmith> Sparks: There would -- because one is semantic markup, and the other really isn't
19:54:25 * jsmith votes for installing the "PressBooks" plugin in fedoramagazine,org, and calling that good :-p
19:54:26 <Sparks> IMO, it would be nice to have some sort of an editor, like what's in WP or Mediawiki, to help mark things up but it isn't necessary.
19:54:30 * jsmith is only half-joking
19:54:45 <Sparks> jsmith: DO IT!
19:55:15 <pbokoc> I think that asciidoc being harder to learn than markdown isn't necessarily a big issue. If we have a wysiwyg editor on the site, it could have a help popup explaining most commonly used syntax
19:55:29 <Sparks> pbokoc: +1
19:55:52 <jhradilek> +1
19:56:22 <jsmith> Sparks: There's always Asciidoctor as well for converting AsciiDoc to to DocBook, etc.
19:56:28 <jhradilek> Plus, we can use templates and even have them in DevAssistant to get people started.
19:57:50 <shaunm_> jsmith: see also ducktype, a lightweight syntax that can do everything mallard can, currently under development
19:58:14 <jsmith> shaunm_: Yeah, I got introduced to that in August by jhradilek :-)
19:58:26 <randomuser> is the idea to still use publican to render $markup ?
19:58:43 <jhradilek> shaunm_: I keep promoting it. :)
19:58:52 <jsmith> Only if it's DocBook, I think... is there a reason to use Publican to render asciidoc/markdown/ducktype?
19:59:07 <shaunm_> <charles_montgomery_burns>eeeeeexcellent</charles_montgomery_burns>
20:00:29 * jsmith wanders back to ${DAYJOB} before he makes any more waves
20:00:43 <shaunm_> markdown seriously limits what you can do. to do anything non-trivial, you have to escape to html. asciidoc is considerably more flexible, though it does have some limits on what kind of nesting you can pull off
20:01:14 <shaunm_> though you might well ask yourself how deeply you really need to nest stuff
20:06:01 <randomuser> I'm really more concerned about the publishing side of the equation.  We can all learn whatever markup, or each use the markup of our choice, if that's in place
20:06:46 <randomuser> and an alternative to publican is a good idea because 1. Nobody wants to set it up. 2. Nobody wants to set it up.  3. We keep all the problems from the existing method, except web.git
20:07:03 <randomuser> ...and not having web.git makes those quirky repairs harder
20:09:18 <randomuser> if you want *easy* we could just do docswiki.fp.o and tell everyone "this is your docs, over here is your process tracker"
20:23:34 <pbokoc> well, yeah, I wanted to say that before; we should probably really focus on making a publishing process that doesn't depend on a Fedora release that died a year ago...
20:55:05 <jsmith> pbokoc: I couldn't agree more
20:55:37 <jsmith> Are any of the Brisbane folks coming to DevConf, by chance?
20:55:57 * jsmith is half-wondering if we need to have a FAD in Brisbane just to get Publican web publishing working the way we want
20:56:04 <pbokoc> no idea, but I don't think so. Last year I don't think anyone did
20:56:10 <pbokoc> or at least I don't know about anyone
21:19:02 <pbokoc> #endmeeting