I read it perfectly fine on my iphone. Turning the device to landscape and zooming so the article text was full width made it an almost ideal reading experience.
That said, the site does desperately need a responsive redesign so that you don't need to do what I just described.
On the topic of copy editing you raise: I wrote a book in DocBook for Manning in 2010. DocBook is XML, so I structured it with opening / end tags on their own line, content in the middle. As you would with a HTML document.
After copy editing multiple chapters, they sent it back to me with all the content on a single line. I was so incredibly upset that they ditched all my painstaking format that I almost abandoned the project there + then.
Not needing to care in the slightest is one of the major value propositions of that sort of syntax, at least IMO. If it does happen to matter for whatever reason that's what formatting tools are for.
The "Writing" section here has huge "draw the rest of the owl" vibes. (I say this as an accomplished author of 10 tech books.)
Yes, it's worth optimising for your productivity. It's not the be all and end all. I've written at my desk with the comfiest chair (A Mirra) I have, and the most ergonomic keyboard for my needs (Ergodox EZ). I write at cafes with just the laptop. I write on the couch at odd but comfortable angles. I write on public transport squished against strangers.
I love using AsciiDoc as the tooling (asciidoctor + friends) give me output that looks decent, and the way I _input_ into that is not mind-breaking like Docbook is. Asciidoctor gives me a PDF which I then style how I like with CSS and then can put on leanpub.com and sell for real dollars.
The way I would put the writing section for tech books is this:
Start with the _topics_ you want to cover. Make these the chapters. Then dive into each topic and figure out what you want to say about the topic. Usually 3-4 main points per chapter. These come out to be your subheadings. Order the chapters from beginner-to-advanced concepts or in a way that makes sense for the book you're writing. For the books I've written it's usually start with a simple base app and then incrementally build things on top of that.
Apologies for being Mr. Negative Guy. I hate folks that do that.
But as somebody who is extremely technical and loves tools and coding, moving to long-form fiction writing, I find that every minute I spend on tooling is _not_ writing. It might be good and necessary, and tools can do some amazing things, but it's not writing.
Fiction writing, at least for me, is a bit of organized struggle with my subconscious. My brain would much rather be coding, writing build scripts, creating a huge cross-layered tagging system, commenting on HN, and so forth. That's because "struggling with your subconscious" is not something we teach or emphasize.
There's a really strong allure of tools, process, and tooling that calls to us when our minds don't want to do the work. Buy the product, learn the tagging, follow the recipe, etc -- it's all about hey, don't do the work, have the tool do the work. Don't be a dummy!
But since I don't know the work myself until I create it, there's no tool or process that's going to do anything but distract. Love my tools, spent a lot of time with them. I spent all day yesterday re-creating and re-factoring my build pipeline from markdown to about a dozen different formats. But that wasn't work, not really. It was avoiding work by doing (hopefully) very useful tangential things.
I'd love to write a tooling/process essay or book. I will not. This is why.
I wonder if your template (love you used GitHub's template tooling!) could also demonstrate that GitHub has a GFA (GitHub Flavored AsciiDoc) by leveraging the env-github directive for things such as your images that otherwise appear as broken in the template:
To others reading along, admonitions or callouts, noted here as key motivations for asciidoc, are supported in quite a few flavors of Markdown, but specifically GitHub Flavored Markdown:
This handles Note, Tip, Important, Warning, Caution.
(After years of incremental work, a suggestion last week complains it's not using mkdocs admonition syntax -- it must be a pain to make custom extensions for a global userbase.)
Why? They've always been this way. I still remember when my friend couldn't see any of my (windows and android at the time) devices but I saw all of his on bluetooth. They've never liked competition.
This is apple, this is how they do business. I don't think anyone using their products will care though, they'll find a way to spin it into something that is good for them.
Off these, I’ve made $65,000USD. That’s over 13 years. None of these books have sold anywhere near as close to the Unicorn Project! (Which imo is fanfic for the tech-inclined)
The money is nice, but hearing from people who’ve read the books (especially those who ask questions!) is the best part.
Huh, maybe it is the friends we make along the way after all.
What an excellent resource! (And yes Outlook is a pain and supports so very little!)
We've tried building email templates for notifications for our apps where I work, and it has typically been a pain. We have since swapped to using mjml (https://mjml.io/) to build the templates, and it's working wonders. The output seems the be the most compatible with all different devices that we've tested on.
The other tool we enjoy using is Litmus (https://litmus.com), which allows you to throw in an email template and see what it looks like on all kinds of apps and devices. Other thread here mentions https://testi.at/ as well, which we've also had success with.
All of these have been really invaluable to designing emails for our apps.
mjml looks really interesting, thanks for sharing. I wish there was a business reason for orgs to care about accessable and machine readable (I guess OCR is a thing now but still) emails.
I've been using Foundation for Emails[1] for the very small number of emails that I've worked on which required more than just a list of img tags, and I really appreciate it for existing because HTML emails have been stuck in ie6 web days.
> I wish there was a business reason for orgs to care about accessable and machine readable emails.
I hope the upcoming EU Accessibility Act will be enough for many organizations to finally make their emails accessible. I disable images by default in my email client, and some emails are pretty much empty without them, without providing any alternative.
> I wish there was a business reason for orgs to care about accessable and machine readable
Isn’t the whole point of sending emails to get the recipient to read them? If the recipient can’t read them, you wasted that money and captured no value. Possibly negative value because you just reminded the recipient of how annoying your website is. “Oh right, that vendor with the full-page modal that I couldn’t dismiss, or was it the vendor that had a pretty site that turned gray three seconds after loading for not discernible reason and wouldn’t let me click anything after that? I’ll just shop at Amazon next time even though they’re more expensive and vaguely evil.”
I assume most email client support email with both html and txt content. If they don't support html or configured not to display it, the txt version is displayed.
We have a html and txt template for each email we send. It's not exactly double the work, but it's appreciated by some of our customers.
I have my email client configured to display messages as plain text. A large fraction of emails that I receive have a text part that is empty or has some placeholder text. Also, senders often generate the text version by taking the HTML version and just stripping all tags, which means that all links are removed. I wish I could configure my client to ignore the text part completely, and instead to convert the HTML part to plain text, which is what it is doing already if there is no text part.
MJML is easily the best tool of its kind and I use it a lot. If anyone is trying to build emails in 2024, it's a major shortcut that helps avoid and mitigate some of HTML email’s biggest headaches.
the mjml components unpack to a very large number of html tags. so depending on how you structure the doc it can exceed the gmail doc size with a surprisingly small amount of content
While we‘re here I‘d also like to recommend react-email[1] which I‘ve been using for building emails for a while now. The components it offers are more than enough and it‘s definitely better than building mails with <!—MSO—> tags every five lines like we did back in my email marketing days.
Kind of. Though if outlook magically goes away we'll still make emails with <table> because most clients still do not support even flex-direction. Outlook is just exceptionally bad with stuff like width:100px working on table elements, but not on <div>, or padding working only on specific elements.
Holy shit all of those are awesome links, I'm working on an internal tool and i like to have clean looking notification and alert emails but its a FUCKING NIGHTMARE because everyone uses either Gmail or Outlook and both handle everything so poorly and... weirdly. And oh my god having to use tables... so many tables.
Yes, the url (https://thebigg.dev/) is correct. I just tested on my phone and it's loading just fine--I have an Android phone and test it on Firefox and Chrome and works just fine. Interesting that it does not load for you...what phone/browser are you testing it on?
Also, sorry! Already bought the domain a while back ;)
That actually kind of makes sense. The framework I'm using (Yew) compiles down to WASM. So the entire website is loaded up-front first. It's like loading an entire app on your browser. The idea is once you load it, it should go really fast.
I’ve been lightly enforcing a rule of my own too: “no agenda, no attenda”