Dear Carrie Anne and Amit
I too have been concerned about the Python documentation being too difficult for students to understand.
To be easy to teach, navigate and to link to in IDEs, the documentation requires a clear and logical structure.
To be easily understandable and accessible to youngsters, the language in the documentation needs to be concise and clear and with a consistent style. This means, in my mind, that although it can be a community endeavour, it needs an agreed structure first and a good copy-editor at the end.
To see what this would involve I have had a go and discovered it will be a big job. Well worth sharing!
I have experimented with a straight html structure but I have no idea if this is the best way of doing this to make it easy to incorporate in IDEs. I suspect XML would be better.
I have produced a nested index system with plain english descriptions provided all the way through but ending in a single page with a logical name that could be used in IDEs. So, for example, the random.choice() function has its own page with the same headings as other functions and is accessed by navigating through built-in modules then random (which has its own description) then then clicking on the choice() link which has its own description.
I have not explored classes and their corresponding methods provided by modules built this way because I think it is pretty easy to see how these can follow the same system.
(I have used an obvious link style so you can clearly see where I have provided examples. This is not a comprehensive Documentation set!!)
Best wishes
Chris
This is a great blog by a teacher in Bath who I believe is on this mailing list. I'm sure she can give you a list, but to start with here is
the post I was referring to.
I hope some teachers will read this and add their requests for good documentation so your offer of help gets snapped up! As Nicholas mentioned, a Python in education website is being formulated. We will need good documentation for it. More details to come!
Thanks,
Carrie Anne.
_______________________________________________
Pythonedu-wg mailing list
Pythonedu-wg@python.orghttps://mail.python.org/mailman/listinfo/pythonedu-wg