Resources Or help on reading Docs.

[pydis-bot]

Originally posted by Adam:

As many of you know, I really struggle to understand docs. Their language is very neutral and professional, usually with minimal amounts of coded examples. So all I see are python classes with parameters I have no idea how to implement or use, as they generally different depending on use case.

Example No 1 - Discord.py rewrites Proxy feature: https://sharpweb.me.uk/i/kym84.png

For people who use the cogs version of discord.py, The idea of using client is never really there. There are no examples of how to implement this into your code, and you are never told where to implement its parameters.

Example No 2 - FBchat modulemodels https://sharpweb.me.uk/i/mkvfq.png As a first project for me, reading these docs was hours upon hours of me smashing my head into a monitor trying to figure out what the hell it meant. Themodels` feature.

The code client.fetchGroupInfo() shown here (https://sharpweb.me.uk/i/iyhh6.png) Was very hard for me to understand at the time, the point I missed being what it returns.

Example No 3 - Imgur HTTP API https://sharpweb.me.uk/i/4ss1o.png Although not python, I was planning on using this as part of my Discord bot, but with no previous experience on this, it was a nightmare. Showing the python version of this just shows a dict, no use-case or code examples that will actually return a result.

Looking at the https://docs.aiohttp.org/en/stable/client_quickstart.html#make-a-request page definitely makes it a lot clearer on how to use aiohttp, and is actually one of the best examples in a doc I've seen

My Suggestions

My first examples with docs were a terrible experience, and has made me scared to touch them ever since, so I have avoided them completely. If my first experience with docs had been better, I think i would have done a lot better.

If a beginners project page is ever created, good example docs would be one of the best things you could add. Showing at least one function from every class in the docs would make it so much easier for beginners to implement into their own code.

Tips of what to read in a doc. For example what it returns, which is a important thing I looked over as a beginner.

Overall

I have exposed myself as pretty stupid in this post, but I feel like I am not the only one that has had problems like this with Docs, and would love for a better way to get started with them :smile:

Sharp

[syntaxaire]

When we create a related page on the new wiki, I will add this link. Leaving it here for now.

https://student.unsw.edu.au/reading-understanding

[lemonsaurus]

I have no idea how to action this, and the images in the original post are no longer working. I'm gonna close it, I don't think it has any value anymore.