handlebars-site
handlebars-site copied to clipboard
wycats
Tooling help / improvements?
I have a couple of notifications sat in my inbox about improving the docs here, and I had been hoping to sit down and take a stab at it. However, I'm not a ruby-ist and have really struggled to figure out how I can run this locally.
I've got as far as a bunch of static .html files, but all the paths to stylesheets etc are wrong, so I'm a bit stuck. I asked my friendly local ruby dev, and have been informed that I've managed to do some 'ruby archaeology' :grin: :grin: :grin:
I have little opinion on the what, but I was wondering if it might be an option to update the tooling in this repo to make it easier to contribute to and update the documentation?
I have no idea whether there's a few simple changes that could be made to make it easier E.g. update the read me with a how-to, or if there's room for switching this to use jekyll or some other static build tool?
The infrastructure is fickle to setup for sure. Even for me locally I have it in a state where I don't want to touch it for fear of breaking my build env :/
I'd like to move the contents here into the handlebars.js repository proper to avoid the "you need to file this bug in that other repository over there" and try to bulletproof the build process to make it less problematic to setup. Added benefit would be automation of the entire release process vs. the manual site update that is required right now.
Ideally we move it to something that is node based like the rest of the ecosystem but I'm not sure how much of a rewrite of the content this would require. For me the questions are:
- What do we move to?
- Who has capacity to do the conversion that entails?
Do you have any recommendations on (1)?
If you want to keep it code based, then I'd say just use straight-up jekyll no fancy stuff :) Keep the docs in /docs or similar, and push the latest version out to gh-pages branch as part of the release process.
If you want to go for a managed solution then I very, very, very highly recommend http://readme.io. They work with OSS, support theming & custom domains, and their tools includes versioning. When you're about to do a new release you fork the current doc version, make your updates & don't make them public until you're ready. There is a built in 'suggest edits' tool, which encourages community contributions. It doesn't solve the manual site update, but it does solve the overhead of managing extra code for your code :)
This is what Ghost uses for http://themes.ghost.org so they already added handlebars syntax highlighting support to their code blocks at my request :stuck_out_tongue_winking_eye:
How has your engagement been with the "suggest edits"? In general it doesn't feel like the handlebars community is very engaged, but we don't make it particularly easy right now.
In general it seems that typos, errors & broken links get hoovered up quite quickly. Not too many people try their hand at larger updates, but then not many people like writing docs. I would say we get more engagement via suggested edits than we did via GitHub pages, but that may also correlate with our growth as a platform :)
Gotcha. I think markdown in the repo is a bit more exciting for me with links back to the github source is a bit more exciting for me. Will try to play around a little bit with both though (when I can make some time from bootstrapping my startup :) ) On Fri, Oct 16, 2015 at 3:30 AM Hannah Wolfe [email protected] wrote:
In general it seems that typos, errors & broken links get hoovered up quite quickly. Not too many people try their hand at larger updates, but then not many people like writing docs. I would say we get more engagement via suggested edits than we did via GitHub pages, but that may also correlate with our growth as a platform :)
— Reply to this email directly or view it on GitHub https://github.com/wycats/handlebars-site/issues/125#issuecomment-148652184 .
It's been a little while, thought I'd check back in here to see if there's any progress / thoughts on moving forward with the docs?
@ErisDS I've had very little time to focus on non-critical issues with Handlebars as I'm currently trying to bootstrap a startup and shipping the product wins over trying to focus on open source work in most cases. I'd say at this point if you had a solution that you wanted to prevent or even if you wanted to take over the docs completely, you'd have my support. Outside of that, I don't think that there will be much movement on this issue in the near term :/
I have added an "integrations" section to the new site, it just needs some love.
http://handlebarsjs.com/installation/integrations.html
