5 ms·

Thanks for this! One of my frustration with tools nowadays is that they aim to be so "user friendly" that actually make things complicated and thus understandin

by _benj 4y ago

Thanks for this! One of my frustration with tools nowadays is that they aim to be so "user friendly" that actually make things complicated and thus understanding how something works, which allows one to be more productive with a tool, is hidden under tons of layers of complexity and simplistic "getting started" that can indeed make an amazing looking website with 1 command, but from there on, trying to figure out _how_ that amazing website works and how can I adapt it for my need is a rough journey!

IceHegel 4y ago
Unless a tool is so ubiquitous and widely used that it becomes a new standard (like JavaScript), over abstraction is a very real problem.
svat 4y ago
Exactly. I ran into this when trying to set up Hugo, and wrote for myself a notes page with the following: # What is Hugo? `hugo` is a program that takes some .md files (ideally, conforming to a certain directory structure) and creates some .html and .xml files (conforming to another directory structure). This is the minimal command: # Create input directory structure to silence warnings mkdir content layouts{,/tags,/categories} touch layouts/home.html layouts/{categories,tags}/list.html # Run hugo: creates public/ and resources/ hugo …and building from there. If you read the Hugo documentation, it talks about all kinds of stuff but doesn't explain anything from the bottom up: apparently the usual way is to start with a pre-existing theme or site as template and edit it, but that's not explained anywhere either. After you eventually learn exactly what Hugo is, it becomes ok to use.
- leetrout 4y ago
  I plan to record a small (4?) series of videos about starting with Hugo from scratch. Would love to hear any pain points you specifically think need to be addressed.
  - projektfu 4y ago
    Being a video is a pain point for me. I much prefer a useful text tutorial with code I can copy, etc. But I don't want to be a choosy beggar so you do you :)
- BossingAround 4y ago
  That's not Hugo's problem, that's a problem with Hugo's docs. Something that pretty much all projects, and most big companies, struggle with. There's very few documentation experts out there. Those who write the docs are either devs who write broken English, or English majors who don't understand a lot of the tech stack. In either case, they usually miss the target persona, and what are the reader's needs. Writing docs is hard :/.
  - MengerSponge 4y ago
    Hot take: The docs are an important part of the product. If you notice that the docs are bad, the product is bad. Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.
    - twodave 4y ago
      I'd even take this hot take up a few more degrees and say the docs quality not only represents the product quality, but also validates it. In other words, you can't know whether your product has a chance of being good unless you're _able_ to write good docs for it.
    - speed_spread 4y ago
      Even hotter take, you can have a well documented shit product and it'll be better in a lot of cases than a quality product with no docs.
      - WesternWind 4y ago
        This is true. Docs, re not necessarily considered important features of the product itself but they make a huge difference. Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.
      - twodave 4y ago
        And if your project is open source and the docs are clear and show good vision, you might even attract folks to come fix your broke-ass code :D
schemescape 4y ago
Yes, I also found it difficult to understand how Hugo worked internally. If you’re ok with NPM, Metalsmith is a trivially simple static site generator, where you just write JavaScript code to customize it (and of course you can plug in templating tools). If you don’t like NPM, but like JS/TS, I started a port/rewrite of Metalsmith for Deno, I can share if anyone’s interested.
- cxr 4y ago
  It's md2blog for anyone who is interested <https://jaredkrinke.github.io/md2blog/ https://jaredkrinke.github.io/md2blog/> The Show HN discussion from 2021: <https://news.ycombinator.com/item?id=29382091 https://news.ycombinator.com/item?id=29382091>
  - schemescape 4y ago
    Specifically, the internal Metalsmith-like core is here: https://deno.land/x/goldsmith@1.2.1 https://deno.land/x/goldsmith@1.2.1 Although I now see that I only documented in-code. It’s very similar to Metalsmith, except based on Deno, in TypeScript, async, and standarized on RegExp instead of a grab bag of globbing libraries. Edit: generated docs link: https://deno.land/x/goldsmith@1.2.1/mod.ts https://deno.land/x/goldsmith@1.2.1/mod.ts
- roblh 4y ago
  Metalsmith is cool! I hadn't heard of it til now but it looks sweet. I actually made something similar except mine isn't designed for static sites specifically. It just takes markdown, parses it into HTML (with code highlighting of course) and stores the html and frontmatter in an in memory sqlite database that gets rebuilt each time you save. Not the most efficient choice, but it makes plugging it into any front end framework like nuxt or next or svelte really easy, particularly if they have server side rendering. I guess it's almost halfway between this and PicoCMS. And you get full text search.
spaniard89277 4y ago
PicoCMS is the real friendly CMS for serving static files. 1. Upload PicoCMS to the least expensive LAMP shared hosting, by FTP. 2. Upload markdown files to /content. Viola. You may also want to download themes or make your own with Twig templating system. IMO if you're a software developer and you can't figure it out in 10 minutes, it isn't really that friendly.
- IanCal 4y ago
  Hmm, that sounds good but when I go to the homepage it gives me buttons for learn more and download, neither of which work and the focus is all messed up. I know it's probably not the CMS part that's broken but if the website for a website builder doesn't work it doesn't inspire confidence.
  - spaniard89277 4y ago
    ? I just checked and it works fine for me
    - IanCal 4y ago
      Seems fine on a desktop, but doesn't work on android chrome for me.

by _benj 4y ago

IceHegel 4y ago

Unless a tool is so ubiquitous and widely used that it becomes a new standard (like JavaScript), over abstraction is a very real problem.

svat 4y ago

Exactly. I ran into this when trying to set up Hugo, and wrote for myself a notes page with the following: # What is Hugo? `hugo` is a program that takes some .md files (ideally, conforming to a certain directory structure) and creates some .html and .xml files (conforming to another directory structure). This is the minimal command: # Create input directory structure to silence warnings mkdir content layouts{,/tags,/categories} touch layouts/home.html layouts/{categories,tags}/list.html # Run hugo: creates public/ and resources/ hugo …and building from there. If you read the Hugo documentation, it talks about all kinds of stuff but doesn't explain anything from the bottom up: apparently the usual way is to start with a pre-existing theme or site as template and edit it, but that's not explained anywhere either. After you eventually learn exactly what Hugo is, it becomes ok to use.

leetrout 4y ago
I plan to record a small (4?) series of videos about starting with Hugo from scratch. Would love to hear any pain points you specifically think need to be addressed.
- projektfu 4y ago
  Being a video is a pain point for me. I much prefer a useful text tutorial with code I can copy, etc. But I don't want to be a choosy beggar so you do you :)
BossingAround 4y ago
That's not Hugo's problem, that's a problem with Hugo's docs. Something that pretty much all projects, and most big companies, struggle with. There's very few documentation experts out there. Those who write the docs are either devs who write broken English, or English majors who don't understand a lot of the tech stack. In either case, they usually miss the target persona, and what are the reader's needs. Writing docs is hard :/.
- MengerSponge 4y ago
  Hot take: The docs are an important part of the product. If you notice that the docs are bad, the product is bad. Docs are hard and thankless, but ¯\_(ツ)_/¯ them's the breaks.
  - twodave 4y ago
    I'd even take this hot take up a few more degrees and say the docs quality not only represents the product quality, but also validates it. In other words, you can't know whether your product has a chance of being good unless you're _able_ to write good docs for it.
  - speed_spread 4y ago
    Even hotter take, you can have a well documented shit product and it'll be better in a lot of cases than a quality product with no docs.
    - WesternWind 4y ago
      This is true. Docs, re not necessarily considered important features of the product itself but they make a huge difference. Other things that I pay attention to are built-in integrations with other tools, the ability to import and export data, familiarity to users, similarity to existing tools, tutorials that leave users confident, and documentation with examples of use cases are all similar factors.
    - twodave 4y ago
      And if your project is open source and the docs are clear and show good vision, you might even attract folks to come fix your broke-ass code :D

schemescape 4y ago

Yes, I also found it difficult to understand how Hugo worked internally. If you’re ok with NPM, Metalsmith is a trivially simple static site generator, where you just write JavaScript code to customize it (and of course you can plug in templating tools). If you don’t like NPM, but like JS/TS, I started a port/rewrite of Metalsmith for Deno, I can share if anyone’s interested.

cxr 4y ago
It's md2blog for anyone who is interested <https://jaredkrinke.github.io/md2blog/ https://jaredkrinke.github.io/md2blog/> The Show HN discussion from 2021: <https://news.ycombinator.com/item?id=29382091 https://news.ycombinator.com/item?id=29382091>
- schemescape 4y ago
  Specifically, the internal Metalsmith-like core is here: https://deno.land/x/goldsmith@1.2.1 https://deno.land/x/goldsmith@1.2.1 Although I now see that I only documented in-code. It’s very similar to Metalsmith, except based on Deno, in TypeScript, async, and standarized on RegExp instead of a grab bag of globbing libraries. Edit: generated docs link: https://deno.land/x/goldsmith@1.2.1/mod.ts https://deno.land/x/goldsmith@1.2.1/mod.ts
roblh 4y ago
Metalsmith is cool! I hadn't heard of it til now but it looks sweet. I actually made something similar except mine isn't designed for static sites specifically. It just takes markdown, parses it into HTML (with code highlighting of course) and stores the html and frontmatter in an in memory sqlite database that gets rebuilt each time you save. Not the most efficient choice, but it makes plugging it into any front end framework like nuxt or next or svelte really easy, particularly if they have server side rendering. I guess it's almost halfway between this and PicoCMS. And you get full text search.

spaniard89277 4y ago

PicoCMS is the real friendly CMS for serving static files. 1. Upload PicoCMS to the least expensive LAMP shared hosting, by FTP. 2. Upload markdown files to /content. Viola. You may also want to download themes or make your own with Twig templating system. IMO if you're a software developer and you can't figure it out in 10 minutes, it isn't really that friendly.

IanCal 4y ago
Hmm, that sounds good but when I go to the homepage it gives me buttons for learn more and download, neither of which work and the focus is all messed up. I know it's probably not the CMS part that's broken but if the website for a website builder doesn't work it doesn't inspire confidence.
- spaniard89277 4y ago
  ? I just checked and it works fine for me
  - IanCal 4y ago
    Seems fine on a desktop, but doesn't work on android chrome for me.