I skimmed through the file and have quite a few suggestions:
- Font makes it an absolute pain to read.
- Text is centered and often has the appearance of a "wall of text".
- Images are too zoomed in and low resolution. It's difficult to get a grasp of what the code does if you only see a small bit of it on screen.
- Rather annoying use of the and symbol (&) in places of the word itself.
- Quite a few sections in the document are useless. You mention texturing, 3D modelling, config editing,... but beyond the title and a few lines, there's nothing to be learned from the document.
- The content is... narrow:
You often write about addon creation methods and then don't explain them or just refer the reader to someone or somewhere else.
In the 3D modelling section you praised Anim8or over Blender for beginners. I know that's subject to personal preferences, but as a beginner in 3D modelling, I found Anim8or a pain in the rear end to use and Blender was like dancing a waltz. You yourself even admit that Blender is a better piece of software in every way, so why would you steer people towards a headache? Anyone who doesn't want to limit their ability to create 3D models will eventually switch to another piece of software like Blender and will therefore need to learn it again from scratch, therefore doubling the learning curve. As for the learning curve, I also disagree. Blender is well documented - quite unlike Anim8or. Searching the Anim8or documentation for any particular subject is a waste of time. On the other hand, Blender also has some very detailed and high quality YouTube tutorials. Anim8or also lacks some vital tools that are essential for 3D and 2D design. You need to get a good UV unwrap tool separately from Anim8or.
"3d meshing is a very large, complex field which could take years to fully explain. In lieu of that, I will just try to explain the absolute basics needed to get in, get out, and make a
good mesh while you’re at it."
Basic, not good.
"The process of making textures is sometimes not given all of the credit it may deserve by the Orbiter community. This is really unfair, as the process itself is difficult, and the right texture or skin can make the difference between okay & amazing with an add-on."
Well, sure, but taking a repaint kit and slapping a Hello Kitty picture on it is not amazing work.
"when the save dialog box is open in
paint.dot.net."
There are other editors, you know... When creating a guide for anything, you should make it so that it's independent of the software people wish to use.
In fact, the first half of the document feels more like a collection of links and programs than a tutorial.
Bottom of page 10:
"Blue text usually indicates anything interactive(ish), Green text is commented, made null & void by // at the beginning of the line, and red usually is used with respect to anything pointed outside of the program itself, like the name of the mesh file for your spacecraft."
Blue are C++ keywords! Nothing interactive about those!
Red usually means plain text. Anything between quotes (" " or ' ') shows in red.
Comments can also be marked with /* and */ for beginning and end of the comment.
"Below this is what I believe is called the class definition. It is a little bit important to note that the term “class” has a different meaning in programming than you might have first thought. The term “class” is often used to describe a specific type of vehicle, like the P-51 Mustang, A6M Zero, Supermarine Spitfire, etc., of which thousands of each type were built"
That is exactly what a C++ class is! You define a class, then you can spawn thousands of copies of the same type of object. To simplify: Class is a blueprint that contains properties and functionality. From the blueprint you can build objects.
"Anyways, your vessels class is defined here as MyVessel, specifically a VESSEL3 class."
No, MyVessel is not VESSEL3. It's an extension of VESSEL3. It has all of the functionality that VESSEL3 has and now you're free to add more.
"Squiggly brackets are used in C++ to package & stack things, especially when placing them in hierarchical order."
They mean scope. A variable declared in a certain scope will only appear in that scope or those "below" it, but not those "above" it. Example:
Code:
...
{
// Scope A
{
// Scope B
int MyInt;
{
// Scope C
}
}
}
Variable MyInt will exist in B and C, but will not exist in A. C is below B and B is below A.
Bottom of page 16:
"The quirky side-effect of this is that you will probably get a negative ISP value at low Venusian altitudes."
That seems a bit unlikely. I don't know what function orbiter uses to calculate Isp as a function of pressure but I highly doubt is linear and I highly doubt it ever reaches 0. Maybe you can find the function somewhere in the documentation (API_Guide.pdf or API_reference.pdf).
"For reasons I don’t fully understand, Orbiters left/right coordinate system will do odd things, so it will take a little bit of juggling to get thruster lights appearing in the right spot."
IIRC, Orbiter uses only left-handed coordinate system. I've never encountered right-handed coordinate system in Orbiter. For the vessel, x+ is right, y+ is up and z+ is forward.
The programming part of the document is a mess. You throw a bunch of information at the user, but at the end of the section, the user has no idea how to actually make anything.
After the programming section ends, you start the Spacecraft 3 section in equally poor detail. If you are gonna mention it in the document, put it at the top.
If you really want to write a programming guide for Orbiter, I suggest you take the API_Guide.pdf as a base and continue from there. That document helped me to begin programming for Orbiter, but after I got started, I found it quite lacking. You could expand it by actually creating a document that would take you through the creation of the vessel from start to finish. You could provide the user with a mesh, textures and images for the 2D panels and guide them through the creation of the entire vessel from scratch.
Also, it's obvious that your knowledge of C++ is somewhat lacking, so don't be afraid to ask OF for help.
. Thankyou
