27 votes

The Markup iceberg

37 comments

  1. [2]
    first-must-burn
    Link
    It was a nice read. I like your enthusiastic tone. I subscribed in my feed reader and look forward to more posts. Some detailed critiques follow, 'cause boy do I got opinions. But I will preface...
    • Exemplary

    It was a nice read. I like your enthusiastic tone. I subscribed in my feed reader and look forward to more posts.

    Some detailed critiques follow, 'cause boy do I got opinions. But I will preface them by saying many styles and approaches exist, so feel free to discard whatever comments don't fit yours.

    Comments

    I noticed at least one typo ("enthousiastic about Markdown") which is not the end of the world, but might be an opportunity to use (and perhaps highlight as a feature) some spellcheck options.

    As far as the content goes, it feels a little unfocused. You might want to think about who your target audience is and then organize your content around what you think is relevant to them. I think your content spans a wide range of possible audiences. You start out with "people who are held back from using Linux by the lack of O365" but then get into Latex syntax, which is almost certainly too advanced for such a person. As it is, the content is probably too technical for a novice user, but advanced users that can handle the more complex syntax are likely to already know about this stuff.

    I would end with a call to action. For example, "you can try Linux with this live distro, and you can install all the tools described here with this set of commands". Or maybe, "Want to know more? Check out my series at Link for a deep dive on installing these tools." As it is, it kind of fizzles at the end, and certainly doesn't tie back into the intro.

    Personally I think "here's an alternative way of working from WYSIWYG editors like O365 and Open Office regardless of platform" might be a more compelling hook for the article. The Linux angle is a bit of a red herring because the benefits of working in Markdown that you tout would be just as valid for Windows users.

    I also think you really glossed over the GitHub integration that creates the blog entries. I assuming that is GitHub pages, but it could just as easily be some GitHub action pushing things to an S3 bucket. Some kind of detail or a link to the tool's getting started guide would make it actionable. Otherwise, the reader does not have any way to engage further. The extension of this comment is to look at the rest of the tools your introducing and how you are linking to them. For example, you link to Marp's homepage, but link to a marp getting started guide or tutorial would probably make it easier for the user.

    While we're on GitHub, another benefit that I don't think you touched on is the value of being able to version control the markdown source to get history, merge changes, revert, etc. Source control is a pretty advanced topic, but I'll argue that if the audience is ready for Latex, they are ready for Git.

    Final thought, I think including screenshots of the output of some of the tools with formatted outputs would make the argument for their use more compelling and concrete.

    11 votes
    1. adutchman
      Link Parent
      I'm glad you liked my post. I have enough ideas to last me a while, so stay tuned! Thank you for the great feedback, I really appreciate it. I have taken your feedback and that of the other...

      I'm glad you liked my post. I have enough ideas to last me a while, so stay tuned! Thank you for the great feedback, I really appreciate it. I have taken your feedback and that of the other commenters and rewritten part of the blog post. I will also keep all the feedback in mind when writing future posts.

      2 votes
  2. [16]
    adutchman
    Link
    This is a blogpost I wrote about how you can use Markdown for way more than most people realise, how I use it for different use-cases and what all the workflows have in common. As a side-note, I...

    This is a blogpost I wrote about how you can use Markdown for way more than most people realise, how I use it for different use-cases and what all the workflows have in common.

    As a side-note, I am new to blogging so I would love to hear what you think about the website, content etc.

    15 votes
    1. [4]
      ChillGrayFox
      Link Parent
      There are a lot of style issues and typos in the first couple of paragraphs: "powerfull" (sp) "often heard rebuttal" should usually be "often-heard rebuttal" "that these programs... are not a true...

      There are a lot of style issues and typos in the first couple of paragraphs:

      • "powerfull" (sp)
      • "often heard rebuttal" should usually be "often-heard rebuttal"
      • "that these programs... are not a true replacement" should be "are not true replacements"
      • "It works, most of the time ™️ but can have terrible issues" - "most of the time" should have either a comma on both sides, or on neither - "it works most of the time but can..." or "It works, most of the time, but can"
      • But what do we mean when we talk about a “Word replacement”. - missing question mark
      • "Libreoffice or Onlyoffice" - in both cases, the "O" is capitalized
      • "[they] where invented" should be "were invented
      • "what if I told you there is another way." missing question mark

      I don't know if it seems to you like I'm nitpicking - I am, but it will extremely strengthen your writing if you nitpick against it for these things. Readers like it when writers appear to have polished their writing sample to an amount of shine, and mistakes like that are one of the few somewhat objective heuristics that are available for their brains to interact with.

      It especially undermines your point that Markup is better than Word for the average user, because Word and LibreOffice would have caught several of these issues.

      12 votes
      1. [2]
        Trobador
        Link Parent
        In their defence, you can very much have a markup editor with a spell checker.

        In their defence, you can very much have a markup editor with a spell checker.

        3 votes
        1. edoceo
          Link Parent
          I write my Markdown in VSCode which has both spell-check and preview features

          I write my Markdown in VSCode which has both spell-check and preview features

          1 vote
      2. adutchman
        (edited )
        Link Parent
        I fully agree with your point since I am normally the person who nitpicks others on their spelling and style. I didn't think about spelling much because I thought it would be fine, but that wasn't...

        I fully agree with your point since I am normally the person who nitpicks others on their spelling and style. I didn't think about spelling much because I thought it would be fine, but that wasn't the case. I have ran everything through LanguageTool by hand for now and I will pay more attention to it myself. I also found out that Languagetool can be self-hosted and Zettlr can connect to it, so I will try that too. With that I will also have a new blog post.

        2 votes
    2. [8]
      Oslypsis
      Link Parent
      So, I'm a graphic designer. For website feedback in terms of looks, I like what you have. I assume it's intentional that when I request the desktop version that it practically stays the same as if...

      So, I'm a graphic designer. For website feedback in terms of looks, I like what you have. I assume it's intentional that when I request the desktop version that it practically stays the same as if it were mobile?

      I noticed you don't add/use pictures of any kind, like a favicon, logo, banners, etc. I'm sure you'd want to keep it feeling the way tildes feels, with a text based focus. But if you'd like, I can help design some imagery for you. A favicon would make the site look more polished and official imo, and a logo maybe just next to the "home" link could work, but ofc imagery isn't necessary for a personal blog.

      It's really nice that you start us off with the dark mode btw! The rest of the site layout and design seems pretty easy to understand and navigate. :)

      7 votes
      1. [7]
        adutchman
        Link Parent
        I put a lot of work into the layout, so I'm glad you like it :). The phone version is intentional, in fact there is no such thing as a mobile and desktop version because I used Tailwind breaking...

        I put a lot of work into the layout, so I'm glad you like it :). The phone version is intentional, in fact there is no such thing as a mobile and desktop version because I used Tailwind breaking points. The relatively small width of the text is mostly because Tailwind Prose comes with max-width-prose and I like the way it looks. The text focus is partially because I like it and partially because I am pretty terrible at graphical design XD. I would love to work with you on a favicon/logo design, you can email me (see my GitHub) if you are up for it.

        1 vote
        1. [6]
          Oslypsis
          Link Parent
          Awesome! :) although, I'm not great at navigating github, and Idk where to find your email address. I don't suppose you could PM me the address?

          Awesome! :) although, I'm not great at navigating github, and Idk where to find your email address. I don't suppose you could PM me the address?

          1 vote
          1. [5]
            adutchman
            Link Parent
            Tildes doesn't have PM I'm afraid. You can find it here in the left bar: https://github.com/teadrinkingprogrammer

            Tildes doesn't have PM I'm afraid. You can find it here in the left bar: https://github.com/teadrinkingprogrammer

            1. [4]
              em-dash
              Link Parent
              Tildes does have PMs.
              1 vote
              1. [3]
                adutchman
                Link Parent
                Oh wow, I missed that completely. Where do I find it in the UI?

                Oh wow, I missed that completely. Where do I find it in the UI?

                1. [2]
                  em-dash
                  Link Parent
                  It's in the sidebar on a user's profile page.

                  It's in the sidebar on a user's profile page.

                  1 vote
                  1. adutchman
                    Link Parent
                    Ah, there you go. Thanks :)

                    Ah, there you go. Thanks :)

    3. [3]
      saturnV
      Link Parent
      your link to zettlr.com is broken for me, website looks good, might want to change the copyright date as well to 2024

      your link to zettlr.com is broken for me, website looks good, might want to change the copyright date as well to 2024

      5 votes
      1. adutchman
        Link Parent
        Thank you for the feedback :)

        Thank you for the feedback :)

        3 votes
      2. Wes
        Link Parent
        The copyright date should be for when the content was first written, not the current date. Though if you'd like, you can put a range. eg. © 2008 - 2024

        The copyright date should be for when the content was first written, not the current date. Though if you'd like, you can put a range. eg. © 2008 - 2024

        3 votes
  3. [10]
    Akir
    Link
    This kind of lost me at the beginning. Bringing up Word and saying that LibreOffice isn't a good enough of a replacement is one thing, but suggesting that markdown is sounds bonkers. LibreOffice...

    This kind of lost me at the beginning. Bringing up Word and saying that LibreOffice isn't a good enough of a replacement is one thing, but suggesting that markdown is sounds bonkers. LibreOffice isn't a good Word replacement only within the framework of the interface or interoperability within an MS Office ecosystem. Suggesting markdown as an alternative is like saying "you can't understand my French because of my American accent, so let me start talking to you in Tagalog instead," when most of the people in the audience don't know what Tagalog is.

    I'm also mildy irked about the bit of conflation about what markdown is with what markdown can be. But I put most of that blame on the concept of markdown itself. In theory it's nice that there is no actual standard because it's flexable. In practice it drives me crazy. One of the chat tools I use for work uses markdown but it uses asterisks for bold text and to get italics you have to surround the phrase with tildes. Every time write something and it doesn't come out how I expected it to I am filled with rage.

    That being said, a blog is a work of personal expression, so don't take my criticisms too harshly.

    12 votes
    1. [4]
      skybrian
      Link Parent
      There is a standard. It's often extended, but it's a base to build on. Weird that this chat tool would change basic syntax.

      There is a standard. It's often extended, but it's a base to build on. Weird that this chat tool would change basic syntax.

      9 votes
      1. [3]
        Akir
        Link Parent
        That’s like saying that Coca-Cola is the standard soda. Sure, it’s common and popular, but it doesn’t work for everyone, some people choose others for arbitrary reasons, and others choose to make...

        That’s like saying that Coca-Cola is the standard soda. Sure, it’s common and popular, but it doesn’t work for everyone, some people choose others for arbitrary reasons, and others choose to make their own.

        6 votes
        1. [2]
          skybrian
          Link Parent
          As they say, the thing about standards is that there are so many to choose from. You can choose tools that follow a standard and they should work together.

          As they say, the thing about standards is that there are so many to choose from.

          You can choose tools that follow a standard and they should work together.

          6 votes
          1. Akir
            Link Parent
            It took a lot out of me to not make that comment just a bare link to this comic. You probably don't need to click it to know which one it is.

            It took a lot out of me to not make that comment just a bare link to this comic. You probably don't need to click it to know which one it is.

            6 votes
    2. [5]
      adutchman
      Link Parent
      That's not really what I intended the blogpost to be about. I explicitly put "Most people just use these editors and call it a day, but what if I told you there is another way [than WYSIWYG...

      That's not really what I intended the blogpost to be about. I explicitly put "Most people just use these editors and call it a day, but what if I told you there is another way [than WYSIWYG editors" in the intro to specify that it is not equivalant. I have found that it can fullfill the same role foe some use-cases and that's what the blogpost is about. As for the standard, I never really run into differences because the main parts stay the same and that's what counts: titles, bold, italic, lists, tables and links.

      7 votes
      1. [2]
        stu2b50
        Link Parent
        Rhetorically the intro is just a bit discombobulated from the body. The intro starts with talking about how many people can't get into Linux because it doesn't have word, and even though...

        Rhetorically the intro is just a bit discombobulated from the body. The intro starts with talking about how many people can't get into Linux because it doesn't have word, and even though openoffice, or google docs exist, it's not word, so that becomes a bottleneck.

        You would then expect the body to describe a solution that problem. But the problem in the intro is not having exactly word - if you're okay with not using exactly word, then you already have perfectly working options. So when it then goes into talking about markdown, it doesn't flow with the intro.

        Markdown wouldn't be a solution to someone who is having difficulties switching to Linux because it doesn't have word; if using Markdown was a viable solution for them, then using an alternative document editor would be as well.

        7 votes
        1. adutchman
          Link Parent
          Thank you for your feedback. Based on your feedback, that of the other commenters and rewritten part of the blog post, especially the introduction. I will also keep all the feedback in mind when...

          Thank you for your feedback. Based on your feedback, that of the other commenters and rewritten part of the blog post, especially the introduction. I will also keep all the feedback in mind when writing future posts.

          1 vote
      2. [2]
        Akir
        Link Parent
        I got that, but what I'm saying is that the early comparison between MS Office and Libreoffice and OnlyOffice didn't seem to match the rest of the content, which made your points much less clear.

        I got that, but what I'm saying is that the early comparison between MS Office and Libreoffice and OnlyOffice didn't seem to match the rest of the content, which made your points much less clear.

        3 votes
        1. adutchman
          Link Parent
          Yeah, that's a fair critisism

          Yeah, that's a fair critisism

          5 votes
  4. [7]
    Jakobeha
    Link
    Typst is a new-ish (beta, but it's been out for a while) alternative to LaTeX for writing papers. My experience using it has been really impressive: it's not as powerful as LaTeX, but it has fast...

    Typst is a new-ish (beta, but it's been out for a while) alternative to LaTeX for writing papers. My experience using it has been really impressive: it's not as powerful as LaTeX, but it has fast live preview, and the syntax is actually intuitive. [It Markdown-like syntax] for bold, italic, list, and header (list and header use different characters than Markdown but otherwise it's the same), and it has a math mode similar to MathTex.

    Unfortunately when a paper needs to use a template defined in LaTeX, LaTeX is the only option. But I hope Typst gets more popular because it definitely seems like a serious contender.

    5 votes
    1. [2]
      skybrian
      Link Parent
      I wonder how good ChatGPT is at converting Typst to LaTeX?

      I wonder how good ChatGPT is at converting Typst to LaTeX?

      1 vote
      1. Jakobeha
        Link Parent
        It’s pretty good: I tried ChatGPT some MathTeX by giving it a couple examples, and it made a couple mistakes, but nonetheless saved me time. Though nowadays I’d use Pandoc, which can now convert...

        It’s pretty good: I tried ChatGPT some MathTeX by giving it a couple examples, and it made a couple mistakes, but nonetheless saved me time.

        Though nowadays I’d use Pandoc, which can now convert LaTeX (or any of its other input formats) to Typst.

        2 votes
    2. [3]
      fxgn
      Link Parent
      Really? Typst is a fully Turing complete language with built in support for programming stuff like loops, functions, etc. I don't see how it is "not as powerful as LaTeX".

      it's not as powerful as LaTeX

      Really? Typst is a fully Turing complete language with built in support for programming stuff like loops, functions, etc. I don't see how it is "not as powerful as LaTeX".

      1 vote
      1. Jakobeha
        Link Parent
        I should clarify: the language itself is powerful enough, it's the third-party support which makes Typst "not as powerful as LaTex". LaTex has decades of packages providing all sorts of...

        I should clarify: the language itself is powerful enough, it's the third-party support which makes Typst "not as powerful as LaTex". LaTex has decades of packages providing all sorts of extensions, some which are complex and surely rely on LaTeX-specific behavior that would make them hard to port.

        Even then, I'm sure Typst fits almost every situation, except when you're working with a team who's more familiar with LaTex, or have to submit in a very specific format which is written in a LaTeX template. Unfortunately those exceptions are pretty common.

        5 votes
      2. tauon
        Link Parent
        Perhaps a lack of extensibility (without having looked into it)? Or the general “ecosystem”, so to speak? A job’s or university’s document template will still be LaTeX (if at all…), so will e.g....

        Perhaps a lack of extensibility (without having looked into it)?

        Or the general “ecosystem”, so to speak? A job’s or university’s document template will still be LaTeX (if at all…), so will e.g. example CVs you can find online, etc.

        Even if it such a “network effect” (like the concept from messaging apps) were the only actual difference in terms of features/functionality, and we both might not think it’s a big issue, or maybe that it doesn’t even count as a valid difference, it could still make using Typst worse for some users.

        2 votes
    3. adutchman
      Link Parent
      I forgot to mention Typst! I have been following the development of it for a while now and I think the design is a lot better than Pandoc + Latex, but it is still in beta and Typst themselves...

      I forgot to mention Typst! I have been following the development of it for a while now and I think the design is a lot better than Pandoc + Latex, but it is still in beta and Typst themselves caution against using it for anything important so I am holding of on it for now.

  5. [2]
    DefiantEmbassy
    Link
    Back when I was a fervent org-mode user, I ended up writing my final year thesis within it, with a lot of tomfoolery to hook up Zotero, and get the LaTeX export to work, and in particular, look...

    Back when I was a fervent org-mode user, I ended up writing my final year thesis within it, with a lot of tomfoolery to hook up Zotero, and get the LaTeX export to work, and in particular, look how I wanted.

    Was the final result good? Yes. Was the writing experience immaculate? God, yes. Writing in raw LaTeX for a primarily text based document just doesn’t sound fun, meanwhile org/emacs is just a wonderful format.

    Would I do it again? Eh. I have no idea if I'd be able to pull an export from the raw org again, as some configuration was baked into my dotfile.

    I do wonder how this experience would compare. Editing in Obsidian would make me happy, don’t know how the Pandoc exporting process would make me feel.

    3 votes
    1. Akir
      Link Parent
      LaTeX gave me the org-mode experience from my point of view. I found it liberating to have a blank screen and have it just be pure text and not have to worry about formatting. For the things that...

      LaTeX gave me the org-mode experience from my point of view. I found it liberating to have a blank screen and have it just be pure text and not have to worry about formatting. For the things that needed to be specially formated, there were macros that were self-explanitory when reading through it. The only thing that made me give it up was that at the time it was rather annoying to convert the resulting DVI file into useful formats (pdftex was just starting to take root at the time, and even then it was fairly limiting) and of course, needing to change away from the defaults meant a minor research project to find out how to accomplish what I wanted to get done. I remember having particular difficulty with a professor who wanted me to submit a paper that was double-spaced, because it would not mesh with a specific kind of citation they wanted.

      At the time I was going through a series of barely-working computers, so getting a working TeX distribution on them became another annoying thing to install, and with so many professors turning to digital submissions where Office format was a requirement, it just wasn't worth the friction and I haven't turned back to it since then.

      2 votes