Manual & Icons

Involved development of the OpenMW construction set.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

Regarding tutorials: There question was never video or written form. We can have both.

For a complex GUI-based application video tutorials kinda make sense. For the 3D editing part even more so. And I don't think it is in question that there are people out there who prefer video tutorials in general.

But if we have people willing the create tutorials in written form then that is fine too. We just have to decide how and where. As mentioned before I would like to keep them out of the manual (that thing is going to get big enough already).

We could create a second tutorial book, but I am not in favour of that. A book kinda suggests a linear order, read from front to back. What we have here is a collection of separate tutorials that are probably going to reference each other to some degree. That suggests to me a graph-structure (i.e. something wiki-like).
User avatar
sjek
Posts: 442
Joined: 22 Nov 2014, 10:51

Re: Manual & Icons

Post by sjek »

modding with the file format is kinda subject
http://forums.bethsoft.com/topic/151827 ... morrowind/

texture modding, fonts, layout editor would be extras around 1.0 and leveled list + savegame handling and gmst's + others possibly vanilla fixes

for openmw
That suggests to me a graph-structure (i.e. something wiki-like).
documenting scripting to wiki and new scripting for dummies could make it. one way would be at least at first go trough 9.0 version and commenting out all the workarounds needed for orignal engine which doesn't anymore apply. using the template would make things easier if possible. getting contact with ghanburighan, yacoby and other could be little problematic.

more of a near 1.0 project as said before. engine bugs are documented in wiki
https://wiki.openmw.org/index.php?title ... cript_bugs
https://wiki.openmw.org/index.php?title=Bugs

and scripts have that implemented list which could be expanded later.
https://wiki.openmw.org/index.php?title ... g_(status)

for the referencing scripts across scripts and variable limitations gone and such would need some example scripts possibly shortening MSFD scripts also

+ activate command not anymore contsrained to onactivate if tree ofc xD
BlueFootedBooby
Posts: 36
Joined: 15 Sep 2013, 16:00
Location: ...here?

Re: Manual & Icons

Post by BlueFootedBooby »

Zini wrote:...
We could create a second tutorial book, but I am not in favour of that. A book kinda suggests a linear order, read from front to back. What we have here is a collection of separate tutorials that are probably going to reference each other to some degree. That suggests to me a graph-structure (i.e. something wiki-like).
I don't know that I agree with this. I think most people are familiar enough with the idea of a reference book that they'd get the right idea. At worst, it'd take a carefully chosen title (eg "Tutorial Anthology" rather than "Step By Step Guide for Using the Editor") and a statement on the first page that emphasizes that it's a collection of tuts rather than one really big one.

It's not a big deal by any stretch of the imagination, I'm just an insufficiently-supervised navel-gazer with two cents to offer. :V
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

The issue here isn't that people may get the wrong idea (could have worded that better). The problem is that the linear structure of a book does not match the structure of the document in question, which would be something more graph-like.
Automatik
Posts: 13
Joined: 25 Jun 2015, 19:31

Re: Manual & Icons

Post by Automatik »

I feel like a wiki is a better idea, since it's not only non-linear, but it's also more accessible than a pdf. You don't need to save it to open it. Also it may be easier to edit.
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

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:
https://www.youtube.com/watch?v=2drymu6-cFw

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 manual.


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, Pandoc and Sphinx 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.
ven
Posts: 8
Joined: 07 Apr 2015, 03:38

Re: Manual & Icons

Post by ven »

HiPhish wrote: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:
https://www.youtube.com/watch?v=2drymu6-cFw

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 manual.


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, Pandoc and Sphinx 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.
I been searching the forum hoping to find some simple mod tutorials. For me anyway, learning by using examples is the easiest way. Then once I get the basics down it is a lot easier to dive into the more in depth stuff. I hope someone actually does make some basic tutorials :D
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

Well, I figured if I don't do it now I never will, so here it is:
https://dl.dropboxusercontent.com/u/223 ... index.html

Someone who has no experience with the CS should try out the tutorial. Tell me if there were any points where you were not sure what to do and how long it took you. Images can be tweaked, they are a bit too large, that's especially useless for the PDF, but it's about the content for now.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

As you noticed work on the manual has stalled, because nobody wants to work on it. Apparently writing manuals is boring.

About the manual/tutorial thing: That is a bit of a pet peeve of me. I wish people would stop calling tutorials manuals or pretend that tutorials can replace manuals. When I start using something new (be that a physical device or a software package) the first thing I go for is definitely a manual that tells me exactly what is what and what can do what; ideally in a style as terse as possible. If I have to sit through a bloody tutorial instead, that usually makes me rage.

Don't get me wrong. I agree that tutorials are useful and I use them myself. But I don't think they can replace a proper manual.

For OpenMW-CS the idea was to have both a manual (in book form) and a collection of tutorials (either wiki articles or YouTube videos or both).
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

I looked over the manual attempt you linked. Looks pretty good (except that I still really hate it being called a manual / the mixing up between tutorial and manual).

I agree that someone with no previous experience in OpenMW-CS should try it out. I also noticed two things:
We can double-click a table cell to edit it, but there is a better way: right-click the row of our new record and chose Edit Record, a new panel will open.
That might be the right place to mention that you also can use a configurable shortcut here instead of using Context Menu -> Edit Record. I believe the default is currently shift double click.
Morrowind uses something called a relational database for game data. If you are not familiar with the term, it means that every type of thing can be expressed as a table: there is a table for objects, a table for enchantments, a table for icons, one for meshes, and so on. Properties of an entry must be simple values, like numbers or text strings. If we want a more complicated property we need to reference an entry from another table.
That is not quite right. Some tables have entire sub-table in them (only editable in the dialogue panel).


I would still prefer to get the manual up to speed first, but if you want to do more tutorials that is fine with me. What are peoples opinion about moving it to the wiki?
Post Reply