AdamsLair
Consider moving to netlify
Summary
Consider moving to netlify to host the documentation website.
Analysis
- Branch deploys! (preview the website on a given branch)
- Faster build
- Faster website (its already quite snappy though)
- Netlify functions for advanced functionality (for features like search)
Not knowing the service you mentioned in detail (they do seem to be more of a generic web project hoster?), I can't really comment on netlify. Let me know if I'm running off on the wrong tangent here.
In general, the current way to host the docs has a few points that I quite like:
- Everything self-contained on GitHub with no external dependencies except for the docs.duality2d.net domain name, which we have anyway.
- Everyone with a GitHub account can edit a page and submit it as a PR with very few clicks.
- Familiar, PR-based contribution workflow.
- Familiar GitHub interface and git concepts for everything.
- Docs are regarded as a project, with issues, milestones, a git history and even forks if necessary. Contributors can be managed with the same tools and in the same scope as those for the main project.
Aside from hosting, there's also a few bits that I think are neat with the environment we get from the current GitHub pages approach, and our implementation using it:
- All docs are in markdown.
- Responsive style that works on any size and aspect ratio.
- Side-by-side existence of different docs versions.
- Site is completely static, with no scripts running or needed at all. Even my privacy plugin / ad blocker remains completely silent, with not a single external URL being queried.
- Jekyll's Liquid may not be the greatest scripting language ever, but it still allows to extend the system quite nicely. That, combined with the HTML / CSS templating approach is a nice combo of being simple, but still extensible.
Overall, I don't really see much need for a whole hosting solution or docs system switch right now to be honest. What we currently have seems quite nice from a tech and maintenance side, with some opportunity for improvement here and there.
Actually we get to keep all the points you mentioned when we move to netlify and some will even work better.
Netlify just offers alot more features aside from being faster in build time and site performance.
For instance Netlify has a nice integration with git so it can even deploy a preview version of a branch on a separate url. You are also not limited to using Jekyll anymore.
With Netlify functions you can take the docs to the next level by adding features such as search as you type etc.
I used Netlify functions to add search to my blog for instance: https://the-photographing-programmer.com/. Its still completely static and even works offline.
Sorry, but this reads a bit like a marketing text 😄 Can you describe in detail:
- What exactly does netlify provide? Does it cost anything?
- Which steps would be necessary to move to netlify?
- What exactly would change for the docs project in terms of (third-party and core team) contribution and maintenance?
Moving to a new, external hosting service is a big step that could mean a lot of work, added dependencies, required knowledge, maintenance overhead, or any combination of them. This is something that needs to be warranted by an equally significant gain in some form.
From what I gather so far, the improvements this change would provide are really nice2have though. Site performance is pretty good already, build times are pretty okay, and Jekyll has (so far at least) not been a limitation we have to endure, but simply the current framework choice. True, that may be subjective, but it definitely gets the job done. Search-as-you-type is neat, but honestly, I can count the number of times I ever used any public docs pages search and not just Google with one hand.
Being able to deploy previews based on branches definitely is neat, but that alone isn't something I'd abandon ship over. With a Jekyll install, you can get the same preview locally. It would be super neat for Pull Requests to review, but still.
Edit: Maybe it makes sense to just defer this conversation to later - you probably intended it to be a future backlog thing anyway and I accidentally made a discussion out of it, despite both of us being busy with unrelated things anyway. So! To avoid draining energy from more important matters, I'll slowly back out here, I guess I added what I had to say anyway. I'll be back when pinged or when it's considered for implementation. Sorry for the distraction!