Overhauling the manual

General Discussion
1

I’d like to propose a community overhaul to the manual. I just tried editing it and I’ve realized its a bit of a pain. Since we’re using a wiki system for the manual why not use the features available to wikis such as sections, links to sections etc. It would make browsing through the manual a more user friendly experience and a better manual might encourage more users to try out panda3d.

The first thing that would be needed in this community project would be to decide upon a style guide to cover variable naming schemes, code formatting, page formatting etc. For this I propose we follow the Python community and adopt the Apple Publication Style Guide, adding anything that we feel is necessary for Panda.

Secondly after settling upon a style guide templates should be created for the wiki that will follow the style guide to make it easier when converting or creating pages for the manual.

Once these are settled I further propose two projects that can be done in parallel.

  1. A page by page scouring of the manual, bringing them in line with the decided style guide and formatting. While the manual is being changed to the new format, additional information from the forums can also be added to make the manual much more complete.

  2. Creating manual pages that show specific implementations of game design patterns for Panda. New content for the manual to supplement the samples provided in Panda. This can help new comers to programming as the samples don’t really show how to use Panda in making a real game, and could provide experienced programmers a base to quickly start a game from.

2

Good suggestions! :slight_smile: Come on people, lets get the manual into shape!

3

I think cleaning off the HTML code out of the manual and replacing it with some sort of wiki mark up should be the first.

4

Hold it, guys. Let’s focus on substance, not style. I couldn’t care less if the manual uses HTML instead of wiki-markup: what I care about is when it says something that’s wrong!!! Or, when it’s missing information about a panda feature! Really, let’s not get caught up in visual perfection… make the manual more informational!

For example, half the attribs are undocumented, and several are documented barely if at all. THAT is a major weakness.

5

it also will be nice to have the class reference as a tree not a alphabetical list.

6

I can see where you’re coming from Josh but how the manual is presented also impacts how useful it is. Having complete, accurate information in the manual and having this information in well laid out pages is what I want to do. Setting a style guide makes the information consistent with each other, making it easier for users to absorb the information.

We could go over the manual while a style guide is being agreed upon. Which areas of the manual do you think needs work on Josh?

7

Question: Can the manual pages please be made case-insensitive? Like if I go to The_scene_Graph it will bring me to The_Scene_Graph? I don’t know if thats hard to do but for such a well-known and popular wiki system it seems like it would be easily configurable.

8

Two main areas I would like to see improved right now. First, I would like to see documentation of every single RenderAttrib. If you have a half-hour to spare, just pick an attrib that’s not documented and add it.

Second, performance tuning. I’m going to start writing the performance tuning chapter today. After I’ve started writing it, you guys can help me flesh it out.

9

I second this request.

10

hehe its so dam big this post cant take it :slight_smile:
www.panda3d.org/manual/index.php/Class_Reference

11

Well, due to the fact that I am not a fan of the wiki markup things, I am pretty happy with the html stuff in the manual.

Two things I want to throw in:

1st: Would be nice to be able to export it as a static document.

2nd: I absolutely second the “content first!”-idea…

Sure, the manual might need a redesign. - Especcially since the cpp-stuff was added. But I prefer having all needed content first before putting too much work into a new layout and presentation style…

Regards, Bigfoot29

12

OK, I’ve been working on the website, the manual, and wikipedia nonstop for days. I’m exhausted.

Could you guys help out by filling in these sections:

Materials
Depth Test and Depth Write
Tinting and Recoloring (ie, ColorAttrib and ColorScaleAttrib)
Alpha Testing (finish it)

13

Whow… take it easy… :slight_smile:

Noone is helped with you being fed up with the work here. :wink:

Noticed the new header (layout).
Hmmm… the german wikipedia entry of Panda3D was deleted. I wonder why… :confused:

Trying to get an answer there. :slight_smile:

Regards, Bigfoot29

14

Finished the materials page. I used some wiki markup as an experiment. I think putting links to the relevant API classes might be a good thing as it would allow users an easy way to delve into the docs for a more thorough understanding of the system.

We appreciate the work you’re putting towards the next release of Panda Josh. Writing manual pages is kind of a pain.

15

Hey guys… I created a new CSS style for the manual, “codeblock”. From now on, code blocks should be written like this:

<pre class="codeblock">
yada yada
</pre>
16

why not ?

17

The difference is that “codeblock” creates a table with a grey background color, margins and padding, whereas does not. “codeblock” is for big block-quotes, whereas is for small inline quotes.

18

Could we also get padding on tables?

19

Padding on what tables?

20

Just general padding to the table cells, set via CSS. It’s a tad bit hard to read tables in the manual right now with the text flush to the edges of the table cell.