19:28:06 #startmeeting Fedora Docs Office Hours 19:28:06 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 Useful Commands: #action #agreed #halp #info #idea #link #topic. 19:28:16 #chair zoglesby pbokoc jsmith Sparks 19:28:16 Current chairs: Sparks jsmith pbokoc randomuser zoglesby 19:28:30 .hellomynameis jsmith 19:28:32 jsmith: jsmith 'Jared Smith' 19:28:38 Greetings, all! 19:29:17 hello jsmith 19:29:19 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 where 'fun' == 'would you just die already' 19:31:14 I sense anger in you, that can't be good for your chi 19:31:46 yes, you're right 19:32:38 I should see this as an interesting new challenge rather than a terrible old problem 19:36:09 that's the spirit! 19:36:18 become a zen master and annoy everyone with your inner peace :)) 19:37:31 zen masters do not embrace futility 19:39:57 I think they do... that thing with the sand garden or whatever 19:40:33 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 but I'm not sure if I can catch him on IRC 19:41:24 So, Sparks got me thinking... 19:41:39 Hear me out for a second, because this is going to be a radical idea... 19:42:07 ... What if we decide it's time to abandon DocBook altogether, and move to MarkDown 19:42:14 no, we're not abolishing the government :)) 19:42:20 So that anyone can write docs in a web gui 19:42:25 jhradilek, ^ 19:42:31 and instantly check it into git 19:42:46 And because we're not using XML, there's no validation to worry about 19:42:52 Please, please, please, not Markdown. 19:42:56 jsmith, we've been kinda talking about something similar, somewhere. I'm not sure Markdown is the right choice though 19:43:02 And it's almost as easy as a Wiki... 19:43:16 jhradilek, RST ? 19:43:19 ... (or perhaps easier, if you prefer MarkDown to whatever wiki syntax you hate) 19:43:21 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 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 randomuser: There's the spirit! 19:44:14 it's getting interesting in here, but i have to eat before an afternoon meeting :( 19:44:18 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 ... and here's the second half of my proposal ... 19:44:45 That what I've proposed is just *phase one* of a two-phased approach 19:44:53 * jhradilek shuts up. 19:45:43 Then for phase two, geeks like us take that and mark it up in DocBook/Mallard/whatever 19:45:57 jsmith: I like the ability to choice. 19:45:59 and turn it into something more ... structured (for lack of a better word) 19:46:06 That way, it's easy for folks to get started -- 19:46:12 -- there's a beginner tier, and an advanced tier 19:46:17 Sparks: What say ye? 19:47:12 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 I mean, I'd be fine with that now, marking it up is fairly easy 19:47:40 we just don't make this obvious anywhere so people probably assume they MUST learn DocBook to contribute 19:47:48 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 We already do -- we just don't advertise it enough 19:48:05 yeah 19:48:21 jhradilek: Yeah, that's fine ... I just find that asciidoc requires a lot more work for a newbie to learn 19:48:37 jhradilek: Plus, there are a lot of people using markdown with github already... 19:48:54 jhradilek: Again, my proposal isn't about picking the *best* tool 19:48:59 jsmith: So does Markdown if you want to use all of it, most people just use what the page suggests. 19:49:11 jhradilek: It's really just running with an earlier comment from Sparks about picking the "most simple" tool 19:50:13 jsmith: No, see, I was too busy watching TableTop. 19:50:44 *le sigh* 19:52:25 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 Sparks: https://github.com/oreillymedia/docbook2asciidoc 19:52:47 I suspect that there wouldn't be too much trouble to go the other way if necessary. 19:53:12 And maybe we could add support to Publican for ASCIIdoc (or whatever the format desired is). 19:53:26 I've been using pandoc to create docx files, it's nice 19:54:04 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 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 jsmith: DO IT! 19:55:15 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 pbokoc: +1 19:55:52 +1 19:56:22 Sparks: There's always Asciidoctor as well for converting AsciiDoc to to DocBook, etc. 19:56:28 Plus, we can use templates and even have them in DevAssistant to get people started. 19:57:50 jsmith: see also ducktype, a lightweight syntax that can do everything mallard can, currently under development 19:58:14 shaunm_: Yeah, I got introduced to that in August by jhradilek :-) 19:58:26 is the idea to still use publican to render $markup ? 19:58:43 shaunm_: I keep promoting it. :) 19:58:52 Only if it's DocBook, I think... is there a reason to use Publican to render asciidoc/markdown/ducktype? 19:59:07 eeeeeexcellent 20:00:29 * jsmith wanders back to ${DAYJOB} before he makes any more waves 20:00:43 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 though you might well ask yourself how deeply you really need to nest stuff 20:06:01 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 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 ...and not having web.git makes those quirky repairs harder 20:09:18 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 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 pbokoc: I couldn't agree more 20:55:37 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 no idea, but I don't think so. Last year I don't think anyone did 20:56:10 or at least I don't know about anyone 21:19:02 #endmeeting