Would you like to have better documentation for Panda3D?

Do you want better documentation?

The Panda3D documentation is good, but I feel like it is missing. I think it should go a bit more into detail on a few of the topics, and on top of that some parts of the docs aren’t complete yet. It is good but it could be better. I am sure I’m not the only one who feels this way. I think we should have all the Panda3D experts join forces and create better documentation, with the community. What do you think?

The documentation is always in need of improvement, and I welcome any effort to help out.

I also have the idea that perhaps we should be using Sphinx backed by a git repository for our documentation instead of our current MediaWiki approach, which might make it easier for people to contribute changes to the documentation. I’d like to collect opinions on that as well.

I’ve said it in chat before but I very much agree that documentation done via github/bitbucket pull requests would work much better, be it sphinx, readthedocs, github pages or self hosted jekyll, etc. No more need to spend time hardening mediawiki and removing spam. Pull requests can also be commented on – changes, additions, and deletions can be discussed and everyone’s leisure.

All these ideas are great, I really think that we should team up and start writing the documentation from scratch in our spare times. Just make a private GitHub/BitBucket repo, and then make it public once it is done. Or, we could go public from the very beginning and maybe, get some help from the community too.

I find the manual to be really good overall, coming from having some existing experience in python.

Puts on teachers hat that being said there are all sorts of additional possibilities. Part of this is that, like it or not, newcommers are at different levels in programming and python experience. I came in with some python experience writing my own irc bot, but there was a lot I didn’t know. Here are some possibilities that could help with accessibility without cluttering the manual.

Some are minor little things. One would be hyperlinks to the api page of specific functions/classes named in the manual, be it linked by hand or some automatic process. This would help teach how to use the API as documentation.

Another would be increasing the verbosity of some of the example code in the manual. The two places that come to mind are the network section and mouse ray clicking. The code snippits are very, very minimal. It would be nice if at the bottom of each of these pages was a complete example from that page of the manual and the previous sections. I can write up a quick example if I explained this poorly. I know when I started I had a hard time combining the multiple manual pages over one topic into a single function/class. Having a “full” example at the bottom would be a nice scaffold without cluttering the main section of the page.

The harder and more time consuming part would be, in addition to the current manual, writing a full Lean Python and Panda3D at the Same Time tutorial. Something akin to inventwithpython.com/ rewritten using panda3d instead of pygame.

I would volunteer for any of this, but I have been hired recently as a full time teacher and I’m busting 60 hour work weeks

There is good tutorial on mygamefast.com but I think it’s too simple, a bit out of date and the project wasn’t finished and now abandoned.

I think, fighting like this can be almost ideal for editorial project. Game mechanics is pretty simple but visualisation may require almost all panda’s common features. I wish to write or contribute code but I have not very much free time up to the end of the year. Maybe in January or February I will be more free and will be able produce some effort which counts.