Write documentation
Closed this issue · 12 comments
I think it would be good if it were clear how to use this package. It would be beneficial if there was a "quick start" section in the readme that shows an example of how to achieve a common task, i.e. what we need to run and what code we need to write.
Later on we can evaluate writing more detailed documentation that explains how to use the more advanced features.
Thanks for your contribution. At least try to make an effort.
Hi. I respect your decision to close this issue. I hope I didn't offend. I don't think anyone owes me writing documentation, in case that's what you felt.
My intention in opening this ticket is that it'll be beneficial if someone were to write documentation, at least showing basic usage. That way if people want to contribute, and they see this item in the issue list, they could claim it and work on it. Is there a reason why that doesn't work for you?
I have no problems with requests or suggestions, but they need to be better defined than just a headline without any motivation. Improve the description and we can reopen this.
Okay, how about now?
Its better. Have you had a look at the main.py file? It gives a complete example of how to utilise the library.
Are you talking about __main__.py? It has code, not text. It doesn't say what it does or what problem it solves. Also, people wouldn't know to look there. If you're interested in making the project easier for outsiders, there should be more information in the readme, in the form of "If you want to achieve this goal, you write this code."
Ok, do you have any good examples to take inspiration from?
Since I still haven't figured out what this package does, it's hard to say. I imagined it lets me control DeCONZ through its REST API using Python. Is that true?
Here's a random example: https://github.com/home-assistant-libs/pytradfri
The documentation isn't amazing, but it's way better than having nothing.
@cool-RR yes it is so you can control Deconz through python, but you still need to implement whatever logic you need on top of it as it only exposes controls and data to be used
Okay good, now that should be written in a clear and detailed way with examples in the readme. Assuming you're interested in people who find this repo to understand how to use it.
@cool-RR I would say that if you can't infer from the code how it's supposed to be used you won't be helped by a general documentation. You are probably not the intended user. Do you even know what a "Python library wrapping deCONZ Rest API for Home-Assistant" means?
Looks like we're not going to agree, so let's drop this discussion.