This summer Tyler migrated the X-Plane scenery SDK documentation to X-Plane’s main wiki. I just put in a series of redirects, so that the old URLs for the top level pages will point to the various wiki sub-categories. The wiki contains the most recent information now, as well as up-to-date download links, etc.
At some point I will try to replace the individual scenery documents (part of the library.php script) with redirects to the appropriate wiki pages; until then I will leave the old site in place.
We have Tyler working for us again for the summer (last summer he did a very nice and much needed rework of the X-Plane manual), and among his projects is cleaning up the mess that is scenery documentation.
We are moving the scenery documentation from their own dedicated site to the X-Plane wiki. As of this writing, as you can tell, it’s a work in progress. There are a few reasons why we decided to consolidate to the wiki:
- The scenery website is the very best of 1995 technology – unmanaged php in a big mess of files. We wanted to get the site under some kind of content management system, and MediaWiki is already working well for us for other docs.
- There is a lot of overlap between modeling techniques for scenery and modeling techniques for airplanes, so having all of the third party authoring docs in one place makes sense.
It’ll be a few more weeks before everything is organized.
Tyler is also reviewing all of the documentation. I have had a lot of trouble trying to document the scenery system, partly because I have been working on it for years, and thus I have no sense of what people don’t know. Since Tyler hadn’t done any scenery work before, he was able to read the documents and go “hey Ben, you keep talking about X but you never defined what it is.” The resulting edits should make the docs a lot clearer.
I’ve been very busy with X-Plane feature development…when the blog is quiet, usually something interesting is getting coded. (Actually this weekend, I’ve just been sick in bed, so…hrm…when the blog gets quiet, perhaps I am infected.)
Just a quick note: if you see any kind of spam or vandalism on the wikis, please let me know immediately. The wiki engine we use (mediaWiki) has some fairly advanced anti-attack capabilities, but they need to be brought in when a problem occurs. Over the last two weeks I’ve cleaned out repeated attacks on the SDK site and one attack on the main site, and it appears that the software installed now is working.
But if more attacks come in, the next step is filting, e.g. programming the wiki to automatically reject posts based on typical off-topic keywords like certain ED drugs, etc. So if you see a post like this, please let me know – I’ll kill the post and set up the anti-spam filter.
I find it very difficult to write good documentation for the X-Plane scenery system and tools. Not only am I not a technical writer by training and not particularly good at explaining what I am thinking in non-technical terms, but since I have been working on the scenery system for over five years, I don’t really have good perspective as to what is complex and what is straightforward.
For this reason, I try to keep my ears open any time an author cannot understand the documentation, cannot find the documentation, or in another way has a problem with the scenery website. These “first experiences” give an idea of the real utility of the docs. Writing a reference for people who know things is not very hard – writing an explanation for new authors is much harder.
One author who was converting from MSFS to X-Plane pointed out a problem with the documentation that I hadn’t realized before – but I think he’s on to something. He pointed out that the information you need to complete a single project is often spread out all over the place. You probably need to look at an overview document, a file format, and a tool manual, each of which describes about 1/3 of the problem. To make it worse, each document assumes you know what the other ones say!
Who would write such poor documentation? A programmer, that’s who. (In other words, em.) In computer programming, the following techniques are all considered good design and essential:
- Breaking a problem into smaller, sections.
- Limited cross-references between these sections as much as possible.
- Keeping the sections independent.
- Not duplicating information (code).
In other words, the docs I have written for the scenery tools are a mess because they are “well factored”, a good thing for a C++ and a really useless thing for humans.
This is definitely not the only problem with the documentation, which also suffers from a lack of clarity, is often incomplete, and could use a lot more pictures. I am a programmer, and I am paid to make X-Plane faster, better, etc. It can be very hard to find the time to work on documentation when the next feature needs to be done. And yet…without documentation, who can use these features?
Now that I’ve at least figured out that factorization is bad, for the short term I am going to try to write “non-factored” documentation. The first test of this will be MeshTool. I am doing a complete rewrite of the MeshTool readme. Like the ac3d readme, MeshTool needs a full large-scale manual of perhaps 10-20 pages, and the task needs to be approached recognizing that the manual is going to contain a huge amount of information.
When I work on the MeshTool manual I will try to approach it from a task perspective, with explanations of the underlying scenery system, rather than a reference perspective that assumes authors might know why the given techniques work. We’ll see if this creates a more usable manual.
Normally I try to make the X-Plane scenery and modeling system as opaque as possible — I want to make sure that nobody ever actually uses the rendering features that I spend weeks and weeks developing.
But the other night I had a little bit too much to drink, got distracted, and posted these:
In all seriousness, I have been trying to find time to put more documentation up on the Wiki. For these features, you will find an explanation of how the planes work, as well as a link to the planes (with plugins) to download, and a link to the plugin source code (on the SDK site, with sample makefiles for 3 operating systems).
Plugins? Do not panic! While plugins are necessary for some of the features demonstrated here, others can be created without additional programming.
BTW, if the existing documentation uses a concept that is not explained anywhere, please email me. I sometimes leave holes in the documentation by accident.
I have recently started leaving pieces of email and notes on the Wiki. To see this mess, just view Category:Unfinished.
The problem is that often I don’t know what people don’t know but want to know. So when I get an email question whose answer is not already posted somewhere, I make a wiki page and dump the info.
This
stub is in response to some work I did this morning. In particular, lights in X-Plane often have visibility much larger than the objects they come with. This used to be true for the cars, but I broke the code in 921 and didn’t notice. In 921 headlights do persist beyond the car object’s visibility distance, but not by much. 930 will fix this, restoring the “string of lights” look on the roads at night.
I’ve also tuned the headlights to be visible from a wider viewing angle, to try to make them more noticeable from above. (In real life, the lights illuminate an area of the pavement, which is visible, but we don’t do this.)
If there is a scenery subject that is poorly or not-at-all documented, shoot me an email and I’ll stub out a Wiki page – it’s a first step to getting comprehensive documentation.
(Note that I have not added pages for tutorial steps like “how do I add a manipulator to my object” because I am doing the tools work for ac3d now … better to write a tutorial for manipulators the easy way with ac3d than to write one on the hard way – editing the OBJ – and changing it later. That is to say, I am trying to documetn tools, not temporary work-arounds!)
Thanks to those who replied to my previous post…and my decision is: to wiki. It’s relatively easy to make the Wiki look as good (and I use the term good loosely) as the non-Wiki scenery website. By comparison, it would be very complex to make the scenery web-site interactive and faster to update. (And update ease is very important – one of the reasons why there is so little documentation on the scenery website is that it is so hard to document.)
So…as a beginning, I have reskinned the wiki. (If you want the old look, create an account and pick the old skin, called “monobook” in your preferences.) If you don’t like the new look, you can send me a new style sheet or even an existing MediaWiki 1.9-compatible skin…I can install it and can select it in your preferences.
I have also installed some extensions that should help add additional flexibility (for example, the Wiki can now have image-based links). Over the next few days I will try to clean up the front page a bit to provide a clearer navigation structure.
One thing we will need on the Wiki is…
WikiGnomes – that is, users who help to organize and polish the content for readability.
In the long term, I would like to migrate scenery.x-plane.com to the Wiki. But for now that is lower priority than creating new documentation.
Posted in News
by
Ben Supnik |
You might not believe this (due to the general lack of scenery system documentation) but I do spend some brain power thinking about X-Plane documentation for third parties!
Consider two approaches to documentation:
My question is: which of these approaches is more “readable” or “clear” to you as a third party? Each one (the formal website vs. the Wiki) has pros and cons, but I can’t judge “usability” of the documentation myself. Is it easier to find things on the website? On the Wiki? Comments welcome!
(I need to decide where to put future documentation, hence the question “which works better for those who read the documentation.)
