Ask HN: What's the best platform for technical writing in 2022?
53 comments
After a long journey jumping around I’ve recently started writing plain HTML files in GitHub Pages with a custom domain and I have been loving it.
I’ve been on WordPress, Blogger, Medium, a custom Vue site, a custom Go server, a Raspberry Pi, the works. Each was either a platform that could rot, or a hobby that could distract me from writing. Raw HTML on GitHub Pages has solved both these problems for me.
I’ve been on WordPress, Blogger, Medium, a custom Vue site, a custom Go server, a Raspberry Pi, the works. Each was either a platform that could rot, or a hobby that could distract me from writing. Raw HTML on GitHub Pages has solved both these problems for me.
* I make https://mataroa.blog/ It’s a simple blogging engine with an import functionality. One idea would be to just import everything there (assuming they are just text files). Eventually automate this process to keep everything up-to-date.
* Similar problem statement by Stavros in this website: https://notes.stavros.io/ He’s using Joplin [1] to write and then exports everything in an mdbook [2].
[1]: https://joplinapp.org/
[2]: https://github.com/rust-lang/mdBook
* Similar problem statement by Stavros in this website: https://notes.stavros.io/ He’s using Joplin [1] to write and then exports everything in an mdbook [2].
[1]: https://joplinapp.org/
[2]: https://github.com/rust-lang/mdBook
I’m probably not the target user for your platform, but it does look interesting.
Do you plan to offer other domain names? Mataroa may or may not be easy to communicate orally, depending on the user’s location.
Do you have any plans for multiple users (authors) on a single blog? I realize this may go against simplicity, but there is a segment for such blogs where posts are authored by different people.
Do you plan to offer other domain names? Mataroa may or may not be easy to communicate orally, depending on the user’s location.
Do you have any plans for multiple users (authors) on a single blog? I realize this may go against simplicity, but there is a segment for such blogs where posts are authored by different people.
I could host a second instance somewhere. Or maybe even other people could! That would also be good in terms of decentralisation as well. I need to find a cool domain name though that people like because mataroa wasn't so much a success given yours and many other people's feedback :D
Multiple authors might be too much for mataroa. But it could be inspiration for another project. Like a mataroa-style Notion alternative.
Multiple authors might be too much for mataroa. But it could be inspiration for another project. Like a mataroa-style Notion alternative.
If you just want to write, I'd go with wordpress and then syndicate to medium. I don't know if you can syndicate to substack.
Set up a mailchimp mailing list account and have the RSS feed publish a newsletter.
You didn't mention wanting to monetize your content, but if you do, then that's when I'd look at substack. In my experience, it's far easier to monetize your content by showing proof of authority for a better job or consulting than by selling access to knowledge. But your niche may be more monetizable than my experience.
Set up a mailchimp mailing list account and have the RSS feed publish a newsletter.
You didn't mention wanting to monetize your content, but if you do, then that's when I'd look at substack. In my experience, it's far easier to monetize your content by showing proof of authority for a better job or consulting than by selling access to knowledge. But your niche may be more monetizable than my experience.
Doom Emacs + org-mode. Export as HTML upload to webpage, lasts forever, doesn't require a bunch of upkeep, and don't get distracted by all the other things.
This is what I was going to suggest, except Vim. Use your favorite editor, learn basic HTML and CSS, get a domain, rent a VPS, set up Apache, rsync your HTML files to your server. You might already know how to do some or all of this, and none of it is difficult.
Personal “blogs” can never be “dead” unless the internet stops working.
Every canned solution, such as Medium, is inferior to this setup in some way: less control and a far worse experience for your readers, at least. And the suggestions here to use GitHub as a platform for publishing your articles? Good lord.
Personal “blogs” can never be “dead” unless the internet stops working.
Every canned solution, such as Medium, is inferior to this setup in some way: less control and a far worse experience for your readers, at least. And the suggestions here to use GitHub as a platform for publishing your articles? Good lord.
This seems more difficult than pushing the static files to netlify via GitHub.
I know that it seems so. When I started doing this I think the dominant browser was called “Mosaic”. In the intervening couple of decades I’ve seen many people, who relied on “simpler” solutions, suffer data loss, exploits, sites disappearing when some company disappeared, sites being disappeared because a company decided they violated a TOS or just didn’t like their content, discovering that their articles were being used to track and advertise to their readers, and so on.
Most of what you said also applies to VPS providers.
There are more scalable ways to host static files without needing to maintain a VPS. You could also move to S3 + cloudfront if you had issues with netlify. I’ve had 0 issues with netlify for years though.
There are more scalable ways to host static files without needing to maintain a VPS. You could also move to S3 + cloudfront if you had issues with netlify. I’ve had 0 issues with netlify for years though.
I realize that, and there may be no rational reason for you to switch to a setup like mine. But, aside from avoiding such things as Wordpress exploits, my approach turned out to have other advantages. Over the years I added to my knowledge and taught myself how to provide things other than static files. Today my readers can use gnuplot in a Jupyter notebook, and interactive Pluto¹ notebooks backed by Julia running on a VPS. No canned solution exists for this, and in fact I had to work with the Pluto developers to iron out some kinks. This is only possible because I have total control over the servers. If you know will only ever want to serve static files, there are simpler options (with potential pitfalls). But those options are also limiting, in case one day you want to do something unusual.
[1] https://github.com/JuliaPluto/PlutoUI.jl
[1] https://github.com/JuliaPluto/PlutoUI.jl
How is that easier than writing markdown or any other language and export to static html using a generator?
More convenient. In doom emacs it’s a single keybinding for exporting. Bugger-all setup required. Org also has good support for re-ordering and structuring of headlines.
In fact that’s what I do, using a generator that I wrote that relies on Pandoc. But you still need to understand basic HTML and CSS.
I use https://obsidian.md now and is nicer than expected. I publish with https://www.getzola.org/ for online stuff.
I am developing https://giteditor.app as I felt that hosting the content on git and publishing with JAMStack is an ideal combination. What I always felt was missing though, was an easy and quick way to create a note without all the git steps.
It depends. For some things, when it gets really technical, I use LaTeX, and I use TeXShop as an editor. It has a nice side-by-side view of the source code and the generated PDF.
For an intranet, something like Atlassian Confluence does the trick (with LucidCharts for complex graphics).
Public web-based consumption, a markdown doc on github usually does the trick, unless you need something fancy, in that case, you kind of need to fall back to HTML.
I've played a bit with Jupyter notebooks, but I haven't done anything serious with it. I need to look at https://github.com/jupyterlite/jupyterlite for complex embeddings.
For an intranet, something like Atlassian Confluence does the trick (with LucidCharts for complex graphics).
Public web-based consumption, a markdown doc on github usually does the trick, unless you need something fancy, in that case, you kind of need to fall back to HTML.
I've played a bit with Jupyter notebooks, but I haven't done anything serious with it. I need to look at https://github.com/jupyterlite/jupyterlite for complex embeddings.
I don’t write but i have always been intrigued about a pipeline for efficiently writing and publishing. I came across https://hemingwayapp.com/ - you can buy the desktop version and it allows you to directly publish to Wordpress or other places. I have never tried it, but it’s supposed to be a minimalist editor. Give it a shot.
Edit - I did buy the app, I have not tried publishing thru it.
Edit - I did buy the app, I have not tried publishing thru it.
The most crucial part is a setup that lowers the barrier to publish.
Something that you like to use regularly.
Something that you like to use regularly.
I had a nice experience using Hugo for https://danielwiese.com and deployed with Github pages - I was really happy with the easy setup and writing process. The other alternative I considered Jekyll.
Also note that https://store.humon.io/ just redirect to https://humon.io/ and there is no way to shop the gear (that is if it is out)
Which Hugo theme are you using?
My solution was to not use a theme proper. Instead added like ~40 lines of HTML and Go templating logic. Then I chose water.css[0] for the layout.
Feel free to check the links in my profile if you want to see what it looks like.
[0] https://watercss.kognise.dev/
Feel free to check the links in my profile if you want to see what it looks like.
[0] https://watercss.kognise.dev/
I would recommend the following that I used so far:
1. Substack - as it is a nice combination between a blog and a newsletter. So anyone that wants to subscribe can do it but also you can just share the article like a normal blog. It supports bringing your own domain which I would recommend from the beginning and also they can export your data but in HTML files. It has basic support for syntax highlighting.
2. Hashnode - it has more support for syntax highlighting, it saves your blog post if you want as markdown directly in Github and it also supports bringing your own domain. The only thing that I don't understand about Hashnode is their business model :)
1. Substack - as it is a nice combination between a blog and a newsletter. So anyone that wants to subscribe can do it but also you can just share the article like a normal blog. It supports bringing your own domain which I would recommend from the beginning and also they can export your data but in HTML files. It has basic support for syntax highlighting.
2. Hashnode - it has more support for syntax highlighting, it saves your blog post if you want as markdown directly in Github and it also supports bringing your own domain. The only thing that I don't understand about Hashnode is their business model :)
I used to publish a personal blog solely in Emacs. Then I upgraded my Emacs version and some quirks I relied on got fixed, so I can't publish anymore. I also got children to take care of, so I can't spend much time taking care of a somewhat brittle configuration.
I'm thinking about either
- containerising an older Emacs version configured just for this,
- hosting something like WordPress on my own, or
- looking for a hosted alternative.
I heard Drutopia was run as a co-operative which seems like a great idea for a writing platform. However, it doesn't seem that way from their website.
If you know of a co-op in this space, let me know!
I'm thinking about either
- containerising an older Emacs version configured just for this,
- hosting something like WordPress on my own, or
- looking for a hosted alternative.
I heard Drutopia was run as a co-operative which seems like a great idea for a writing platform. However, it doesn't seem that way from their website.
If you know of a co-op in this space, let me know!
pandoc can convert org-mode to html - perhaps that and github with netlify integration would be easiest (or just github pages)? If you only have static content then wordpress would be overkill.
Self hosted Wordpress on a cloud VPS for around $5 / mo.
Build an email newsletter.
Build an email newsletter.
I feel like I might be alone in this, but I find Github + some markdown docs organised into folders to be perfectly fine. Redirect a personal domain to your github repo if you really want, I personally don't bother.
People can clone/fork it, open PR's, see revision history, and its very portable. Probably a terrible choice for natural search discovery though, I assume so maybe not ideal if you want people to be able to just stumble across it while searching.
People can clone/fork it, open PR's, see revision history, and its very portable. Probably a terrible choice for natural search discovery though, I assume so maybe not ideal if you want people to be able to just stumble across it while searching.
It depends.
Self-publishing is not always the best option. Maybe you can start writing for a well established magazine/blog. This may help you to build your 'audience'.
If you want to go on your own, I think the best is first to define what are your goals, from that you can choose if your best option is a blog, a newsletter or a book.
Every platform has its advantages and big disadvantages but choosing one is a matter of your audience's preferred channel to stay in contact with your work.
Self-publishing is not always the best option. Maybe you can start writing for a well established magazine/blog. This may help you to build your 'audience'.
If you want to go on your own, I think the best is first to define what are your goals, from that you can choose if your best option is a blog, a newsletter or a book.
Every platform has its advantages and big disadvantages but choosing one is a matter of your audience's preferred channel to stay in contact with your work.
Did I miss the EMACS post? Cause you know it’s coming.
Yep, it happened - https://news.ycombinator.com/item?id=30898638
My preference is to use Hugo on my own domains.
I keep my repos on GitHub. For deployment I use AWS Amplify, which is dirt cheap and incredibly convenient. No maintenance needed at all. It just works (once you have learned Hugo).
Addendum: If you don’t like GitHub, you can self-host your Git repos instead. If you don’t like AWS, you can instead use a small VPS at whatever provider you prefer.
I keep my repos on GitHub. For deployment I use AWS Amplify, which is dirt cheap and incredibly convenient. No maintenance needed at all. It just works (once you have learned Hugo).
Addendum: If you don’t like GitHub, you can self-host your Git repos instead. If you don’t like AWS, you can instead use a small VPS at whatever provider you prefer.
I feel you should instead look for paying jobs contributing to existing blogs that have high readership. Baeldung.com for one example.
I'm building pagespace.app to address this need for myself as I was also looking for a place to share knowledge that spans multiple pages (with the option of selling via subscriptions or one-off purchases). Would love to hear what I can do to make the platform attractive for this use-case!
Still waiting for the last magical but portable CI/CO conversion step of dropping in a Markdown and getting the SSG website.
GitHub has one CI but is only output is to GitHub Pages (username.GitHub.io) and only with Pelican SSG.
GitHub has one CI but is only output is to GitHub Pages (username.GitHub.io) and only with Pelican SSG.
Be sure to take a look at https://news.ycombinator.com/item?id=30714647
This is maybe what you're looking for -- https://neuron.zettel.page/
I use a minimalistic Jekyll build hosted on Github pages. definitely not self hosted, but takes maybe an hour to setup with a custom domain
the best platform is your own (website) platform
I use iA Writer, it uses markdown. It's quite a minimalist experience, export to html and pdf is available.
Your own site
I've switched recently from WordPress to Jekyll on GitHub.
Sign up to wordpress.com, find a decent looking theme, done.
If you’re doing technical writing for clients, they’ll frequently want your submission in Word format.
For blog writing Medium is decent. Wordpress isn’t bad either.
For blog writing Medium is decent. Wordpress isn’t bad either.
HTML files.
TeX
I think, now are strange times, looks like for really wide distribution, need to switch to video (podcast) format - youtube, tiktok, share podcasts through app stores (Apple/Google/Sony).
So, writing will become screenwriting, or make presentations.
Podcasts, are for people, who listen them while commute, or while waiting in queue, or while do gym exercises, or something like these.
For just text format, I think, just upload to github is good enough for many cases.
But if you want to see real value of your texts, mind about make small books for read on Amazon Kindle, or other reading platform (now Apple have such service, and Google, and many smaller companies). May be good fit Patreon. Mean, if people pay for your work, they really value your work.
So, writing will become screenwriting, or make presentations.
Podcasts, are for people, who listen them while commute, or while waiting in queue, or while do gym exercises, or something like these.
For just text format, I think, just upload to github is good enough for many cases.
But if you want to see real value of your texts, mind about make small books for read on Amazon Kindle, or other reading platform (now Apple have such service, and Google, and many smaller companies). May be good fit Patreon. Mean, if people pay for your work, they really value your work.
Are personal blogs dead? Medium? Substack? Something else entirely?