I’ve been trying to setup the SqueezeBox binding today and after reading a bunch of forum topics I think there is something incorrect in the examples shown in the binding documentation.
Now my question, is there an EASY way to update the documentation? I’d like to help out but I’m not going to be inclined to if it’s not easy. With no real development experience as soon as I read that I need to install Jekyll immediately I’m like… “This is too hard”…
Maybe in the documentation we need a “Dummies Guide to Contributing to Documentation” that people can follow?
The easiest way to change the doc ist fork the git repo, make a new Branch.
To fork and create a Branch just open the readme to edit it in the git webview change something and write a fitting commit massage and commit it. When you are happy with your changes start a pull request.
For a sophisticated markup editor I use to edit the readme with https://dillinger.io after a have new Branch.
What you should note is that the binding documentation is contained in the binding source projects as the README.md. I agree that this could be described in more detail, but there is anyhow still a lot of work to do on the documentation infrastructure…
Having to install Jekyll and Ruby to edit docs make it not an option for me…
I thought I’d try edit the readme.md file in the Squeezebox binding folder and then saw this which made me think I shouldn’t be editing the file this way even though it appears I can?
But you are lucky here.
You found that comment before starting a pull request.
When i have to tell people that their work is good, but in the wrong file that can be frustrating for sure.
You can for sure edit them without installing it, but if you want to test how it looks,
an installation or at least the vagrant machine would be useful.
Agree here.
The process of how documentation is generated and especially how external sources are grabbed and where they are stored is nearly not documented.
You have to look through the grooy script, the maven pom.xml and other files.
And that’s till hard for me who is not that familiar with maven and doesn’t work with groovy.
I think it is way more difficult to a beginner.
Maybe it would be a better option to split the docs repo in one where doc files are edited and one special repo which collects the docs repo maste and the external files like binding docs.
I think it is confusing for beginners to hava repo where some files might be edited and some must not be edited.
If there are only the editable files available they would directly ask why the binding doc isnt there and where they should go to improve it.
@Confectrician
So am I understanding you in that I shouldn’t be editing the documentation in the documentation project but I should actually be finding the squeezebox binding project and make my change there?
