>> 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 like the way how Symfony doc is working. It is using rST (see http://symfony.com/doc/current/contributing/documentation/format.html) and Github pull requests to make changes. I have made a few contributions to the Symfony Doc and I like the workflow. Only one thing I am missing there - something like http://rst.ninjs.org/ where you can test your changes easily without setup a whole building-application to generate the doc for testing. Best regards Christian
