1. 15
  1.  

  2. 5

    At its launch, the content is stored in HTML format. This is OK — we all know a little HTML — but it is not the most convenient format to edit and write, especially if you are creating a sizable new page from scratch. Most people find Markdown easier to write than HTML, so we want to eventually move to storing our core content in Markdown (or maybe some other format) rather than HTML.

    I suspect they will find this hard. Markdown works great when your needs are simple, like entering a comment on a website. I wouldn’t like to prepare a big set of interlinked documents with it. Depending on which specific tool you use you’ll run into problems like:

    • no support for front matter (title, author, other metadata). If it does have support for front matter, good luck getting that into the title, meta description, etc tags without some other kind of templating on top
    • very limited support for facilitating styling (eg adding a class to a table, which the most popular Python markdown library can’t do)
    • no ability to have macros/sub-fragments, for example when you want some kind of common element midway down the page.

    There are other markup languages that can do all of this but they don’t have the popularity of markdown or the simplicity. Sphinx’s restructured text can do all of this, but I have to look up the syntax all the time and all of the cheatsheets that rank well in google have problems. Curious to see what they do.

    1. 2

      I think restructured text is also interesting but suffers a lot from the surrounding infrastructure.

      Sphinx is really thankless work, and I appreciate all that’s gone into it, but from the maintainer’s mouth themselves, it’s not meant to be used as a library, just an application. And ReST without Sphinx and its extensions doesn’t go very far.

      It would be amazing if this somehow lead to some investment into ReST being more usable as a general tool instead of, effectively, just the “sphinx markup language for python docs”

      1. 2

        I feel the exact other way around. I don’t really like RST and don’t know anyone who does really like it but many people use it because Sphinx is so good.

    2. 3

      This argument is annoying, because the differences come from people’s psychological profiles.

      If you do something wrong on a standard wiki, like the old MDN, your changes get reverted. Some people are okay with that, but a lot of people abhor, or may even be devastated, by having their work quietly reverted after they thought it was accepted. Other people prefer the classic wiki, to the point that they explicitly say that projects using “pessimistic merging” are doing it wrong. Do you prefer asking permission, or asking forgiveness? Are you Bold, or Risk-Averse?

      There are way too much categorical judgments for something that’s so subjective as this.

      1. 2

        Between this and the OpenTTD project rolling their own wiki engine intended for git, I wonder if they’re not considering the needs/abilities. It seems somewhat biased from the developer perspective, someone intimately familar with git, over the people who aren’t/are lazy and want to do it from a browser. That’s something MediaWiki did well (which OpenTTD migrated from).