Documentation Clarity

[mredig]

I say all this with a great desire to use the project, and a decent amount of confusion to get it up and running, with the greatest amount of respect! I ultimately passed on using the project due to running out of time to troubleshoot, but I'd love to use it and a few small documentation improvements I believe would really help.

I think the readme would greatly benefit from focusing on the golden path first: how do you expect the users to use this project 99% of the time?

I would then suggest moving the separate troubleshooting steps either all to the end of the readme or to another markdown file.

An example of this is the macvlan portion;

You don't need the macvlan bridge if your host does not need to talk to the container!

Okay, so what do I do if I don't care about host access? The only instructions are for using macvlan. Is macvlan the expected way to use it? Or is this a sidebar for those who do need it, but other are supposed to just skip over some portion of the doc?

Also, even with following the instructions, there appears to be an issue with the provided example bash sub shell script:

sudo -- bash -c '(
dhclient -r $eth && ip addr flush dev $eth && ip neigh flush all
dhclient mac0 && service resolvconf restart || dhclient $eth
)'

It references $eth, but $eth is not accessible to this subshell. For example:

eth="foo"
sudo -- bash -c '(
echo $eth - this is the value
)'
# echos " - this is the value"

It would work if you did

eth="foo"
sudo -- bash -c "echo \"$eth - this is the value\" && secondCommandForExample"
# outputs:
# foo - this is the value
# second command output

It also took me a while to realize these were bash commands. Maybe it would be best to put this all in a script that the user can run called something like demo_example.sh or something?

Also, it still didn't see my Brother USB printer even though I used that volume trick mentioned (which I fully admit may have been pebkac as I got it to work in a personally built container before I found this project, so I might have just set it up wrong with all the iterated attempts).

I feel bad requesting these changes and not just making a PR, but I don't feel comfortable making a PR unless I can at LEAST get it to work myself.

Ultimately, I don't know how helpful my suggestions are since I wasn't able to get it to work, but I ultimately felt like I was jumping all over the readme instead of generally starting at the top and moving down as I progressed.

Again, I feel really bad just complaining! I hope this is received as constructive feedback and not just whining. :) Maybe I might be able to make a couple real contributions if I can get it to work eventually :D

[DrPsychick]

All good, you're making a good point and revealing some "bugs" in the docs, that's helpful!

If you want to contribute, feel free to open a PR that proposes fixes to the docs - when you get it working without macvlan.

[Xu-Xihe]

That's what I think. What the users commonly wanted is to use a printer shared by Windows with Airprint in their wlan. So I recommend that resorting the readme file could be a good idea. I had already successfully printed the test file. But when I looked down, I found I need to do them again. Also, add some details about how to run the commands could help a lot. I really spent time to interpret how to use them. Just a piece of tip like save them into a .sh file to run would make sense.