What's the state of the OpenMW CS manual? The built PDF has only 16 pages and the date says December 2013, although that might be just an oversight.
I tried the CS the first time today to create a simple mod and I didn't find the manual to be of that much use, it's too "academic". What I mean is that it is structured like a textbook that wants you to teach how the program works, rather than how to use it. Imagine you buy a toaster and you want to make some toast, what's the first thing you want from the manual? You want to know how to simply toast bread, you don't want to learn of all the million features of the toaster. Those features still need to be explained, but later. In the OpenMW CS manual I shouldn't have to scroll all the way to the bottom to find out how to search the items list for rings.
Here is how I would structure the manual: there would be two "parts", a tutorial part and an in-depth manual. The tutorial would be just one or two chapter and walk the user through a simple mod. My mod is a ring that gives the player permanent night vision while being worn. There is no complex 3D editing or scripting involved and it teaches the user how tables work, how to create new entries, how they are connected and how to employ very simple filters. Because the mod is so simple we don't need to create new filters. In the end the player would have a completely new item after only about 15 minutes of modding and a good understanding of the underlying principles. This tutorial would be only about creating the ring, if the player wants to use it in the game they have to instantiate it through the console.
The second tutorial could then be about placing the new ring into the game world. We could add it to an existing cell, place it in a chest or give it to vendors. I haven't done that, so I don't know how complicated it would be.
The third and final tutorial would go into scripting, we would replicate the permanent night vision without using a ring and make it adjustable. Maybe make it so that night vision is a power that Khajiit and vampires can toggle by pressing a key on the keyboard instead of a spell or something like that. Similar to this Skyrim mod:
I am not sure about the third one, I haven't done any scripting, so if that's too complicated scrap it. The idea is to have small showcase tutorials that can produce a good result in less than half an hour starting with zero knowledge about the CS. Knowledge of Morrowind would of course be required. There is no particular reason I picked Night Vision, I just wanted something that's cute to show off, plus it's useful for people with glossy screen who find the game too dark, even with torches.
Each tutorial would be one chapter, the rest of the chapters would be a proper reference manual. I find it much easier to read through a reference manual when I can say "oh yeah, I have seen that before". I would not focus on any topic too deeply, there is no need to explain how filters work, only how I can filter all the items for things that are rings.
When the topic of a manual was brought up originally I was against a wiki and I still hold that opinion. A wiki is good if you want to read about one specific thing, like Riemannian manifolds
, but it's useless if you want to actually learn about differential geometry. A wiki is like handing someone a loose list of papers and telling them to figure out how it all fits together. I wouldn't separate the tutorials from the rest either, the chapters are very short and serve as a prelude. I have found this approach to work very well with the pfg/tikZ
On another note, I still disagree with the use of LaTeX for writing the source of the manual. LaTeX is a very low-level format intended for print or PDF. We would want to manual to be readable in different formats, such as HTML, ePub and of course PDF. LaTeX can be converted to those, but it's a messy process. A high-level format would be better suited and I propose reStructedText
. It's similar to Markdown in readability, but it has a lot of formatting features that Markdown lacks. It can be processed by Docutils
to generate lower-level formats. It is much easier to write in because you won't have to deal with LaTeX's package hell and trying to wrestle the formatting. You can still do that after converting reST to LaTeX if you don't like the default though.
If there is interest I can write the first tutorial and convert the existing manual to reST, then you can decide.