Re: Getting more people involved.. bye bye Docbook

On Mon, Aug 12, 2013 at 11:42 PM, Christian Stoller <stoller@leonex.de> wrote: >>> At work we chose reStructuredText[1], because it gives you way more >>> elements than markdown and is only slighter harder to write. Plain >>> markdown e.g. has no tables, and definition lists, while rST has it out >>> of the box. >> >> >> That is pretty much exactly why I didn't want to use it. >> It was just to much. I actually need to learn the syntax before I can write it. >> >> I don't want the the strong semantics relations anymore. Dirt simple is the new plan. >> >> Yes, we do need to introduce some new stuff - like tables for changelogs >> (which are already included in the example document I attached). >> We also need to introduce magical elements (which are already included >> in the example document I attached) which cross link functions, types, >> constants, whatever. >> These magical elements are all confined in the linking marker [], and >> I hope they have obvious meaning: >> >> [TYPE:FALSE] >> [CONSTANT:HTML_SPECIALCHARS] >> [SNIPPET:RETURN.FALSEPROBLEM] >> >> Python for example also uses rST (or whatever the current acronym for it is). >> I know it is a decent format, but I don't want people needing to read some >> primer explaining all the details and gotchas before they can do stuff. > > Hi Hannes, > > I really like Markdown and like to use it on Github, because it's so easy. But I think > when it comes to documentation Markdown is not enough. You already said: > - "Yes, we do need to introduce some new stuff" > - "We also need to introduce magical elements" > > This means that the users/writers of doc have to learn the syntax anyway. So in my opinion it > would be easier to teach them rST+Less-Extra-Rules than Mardown+More-Extra-Rules. > I'm not planning on teaching anyone anything. If that is needed then this experiment has failed. http://p.cweiske.de/51/raw/function.strpos.rst vs https://raw.github.com/bjori/bjori.github.com/master/function.strpos.md Which one feels more natural and easier to guess what happens? Now look at http://p.cweiske.de/51/raw/function.strpos.rst.html vs http://bjori.github.io/strpos.html Did you correctly guess what would happen in one or the other? -Hannes