Manual & Icons

Involved development of the OpenMW construction set.
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

Just to clarify, I do not intend to make the tutorials a substitute for the manual. Maybe a better term would be "a tour through the CS" where you visit some of its major features and end up with a simple product before diving into the actual meat. The pgf/TikZ manual I linked above does that. The official C++ and Swift books also first have a tour through the language before diving into deeper topics.

The tutorials are meant to be very simple, just to get your feet wet. I don't intend to cover the entire CS that way. My problem was that I had never modded Morrowind, so this was literally my first mod and I wrote the tutorial because I found the current manual to be too academic. There is nothing wrong with being academic, but it's more comfortable to jump into the water after you have gotten your feet wet first.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Manual & Icons

Post by psi29a »

I really like what you've done HiPhish, it takes time to do stuff like this. I would liken it to a "Quickstart Guide to OpenMW-CS" which I'm sure is both easily accessible (not academic) and attention getting. The first thing that people read about actually "using" it.

Showing by example is great.

Moving it to the wiki makes sense, that is what it is there for it.
Antsan
Posts: 47
Joined: 13 Mar 2014, 11:15

Re: Manual & Icons

Post by Antsan »

Zini wrote: 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).
I think for a manual/reference a wiki would be more appropriate. Take a look at the Common Lisp HyperSpec. It's easy to navigate and thus usable as a reference and a specification. As far as I know it's also written in LaTeX, which is a horrible language[1].

Tutorials on the other hand are serial in nature – they tell you what to do in which order.

I am not sure what would be better about having it the other way around. Why is a manual where order doesn't really matter (because the described ting itself isn't ordered) a book, and a tutorial, where order is everything, a wiki?

Organizing tutorials in a wiki would, of course, make more sense.

[1]
Spoiler: Show
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: Manual & Icons

Post by AnyOldName3 »

In my experience, LaTeX is a lot easier in TeXstudio than anything else I've tried, as it has really good error correction, so you can write something resembling what you want, and get a load of errors, but still end up with the output you intended. This is a non-solution when people ask for the source as well as a compiled document, though, as it inevitably won't compile for them.
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

Zini wrote:...
OK, I have updated it with your suggestions. I have also changed the two/three tutorial chapters into one chapter called "tour" with two/three sections. That should make it clear that the tutorials are only an introduction.
Antsan wrote:...
Navigation should be no problem, you can do document-internal hyperlinks in reStructuredText, those can be implemented in the HTML or PDF output.

About LaTeX, it's a nice system if you are content with the defaults and it's the most useful for mathematicians. For anything else you will find yourself in package hell, trying to wrestle it into doing what you want. That's why I have chosen a higher-level language, the converter can take care of LaTeX. Ideally what I would like would be some sort of template system where you have your TeX (no LaTeX) template with placeholders and your source in reST. Then you run the converter and it puts the two together. I am using Pelican to do something similar for HTML pages.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

@Antsan I don't agree with your position about what is serial and what isn't.

Tutorials are by nature non-serial. Okay, you can have a long tutorial that is split into a series of tutorials. But generally tutorials can cover a wide range of topics that the user should be able to read in any order he wishes (or even skip some).

A wiki for the manual would be okay, but I don't see a problem with the serial format. As I see it the main purpose of the manual is to inform the user about the capabilities of the editor and provide general orientation. I at least would read it from front to back and then use tutorials to figure out how to do specific tasks. Of course the manual would also be used to look up things from time to time. But a table of content will do that job.

@HiPhish: The distinction between the tutorials and "a tour through OpenMW-CS" seems arbitrary to me. I would consider this tour as just a series of introductory tutorials.

OGRE provides a relative good example of what I mean. There is a sequence of basic tutorials that introduce the user gradually to the core concepts and then there are various advances tutorials that demonstrate specific tasks.
Antsan
Posts: 47
Joined: 13 Mar 2014, 11:15

Re: Manual & Icons

Post by Antsan »

HiPhish wrote:
Zini wrote:...
OK, I have updated it with your suggestions. I have also changed the two/three tutorial chapters into one chapter called "tour" with two/three sections. That should make it clear that the tutorials are only an introduction.
Antsan wrote:...
Navigation should be no problem, you can do document-internal hyperlinks in reStructuredText, those can be implemented in the HTML or PDF output.
I know that, I am just confused about the reasoning behind making tutorials wikis and the manual/reference a book. If both have document-internal hyperlinks, there isn't that much of a difference either way, especially since there is no reason to put different topics in the manual into a specific order.
About LaTeX, it's a nice system if you are content with the defaults and it's the most useful for mathematicians. For anything else you will find yourself in package hell, trying to wrestle it into doing what you want. That's why I have chosen a higher-level language, the converter can take care of LaTeX. Ideally what I would like would be some sort of template system where you have your TeX (no LaTeX) template with placeholders and your source in reST. Then you run the converter and it puts the two together. I am using Pelican to do something similar for HTML pages.
I wanted to use a Common Lisp library for generating docbook-xml (because xml itself is horribly verbose), but there was a bug in docbook-xml where ampersands weren't escaped correctly in the transformation from docbook-xml to TeX, at least not when they were the only thing in a title, which is really annoying when you're trying to write a section explaining the '&' operator.
I'll have a look at reStructuredText. Looks good so far, although I really liked the explicit document structure docbook-xml allows for. Having a subsection inside a supersection just seems more reasonable than having it under the supersection.
Zini wrote:@Antsan I don't agree with your position about what is serial and what isn't.

Tutorials are by nature non-serial. Okay, you can have a long tutorial that is split into a series of tutorials. But generally tutorials can cover a wide range of topics that the user should be able to read in any order he wishes (or even skip some).
I think we assign different meanings to the word "tutorial". A tutorial (singular) is intended to be didactic. That means that the author needs to have a didactic intend first, which must rely on some assumption on how much the reader already knows before reading the tutorial. He then builds upon that previous knowledge in an organized manner, thus a tutorial needs to be ordered, at least partially (with branching paths, for example).
If the individual parts are independent enough of each other to be put into an arbitrary order, it's not one tutorial but a collection of tutorials. You yourself seem to use the word in that manner:
I would consider this tour as just a series of introductory tutorials.
And to quote Wikipedia on the matter:
Tutorials usually have the following characteristics:

A presentation of the view usually explaining and showing the user the user interface
A demonstration of a process, using examples to show how a workflow or process is completed; often broken up into discrete modules or sections.
Some method of review that reinforces or tests understanding of the content in the related module or section.
A transition to additional modules or sections that builds on the instructions already provided. Tutorials can be linear or branching.
So tutorials are very obviously not non-serial by nature.

Writing the OpenMW-CS tutorial would be overkill, as it is hardly a tool that is intended to be used by one person without any collaboration at all – I mean, scripting and landscaping are very different tasks and there are many more in there. Thus you don't write one tutorial that contains both of these tasks but one tutorials for each.

Putting multiple tutorials into a wiki is fine, as I already wrote, but the wiki format is hardly conductive to a tutorial. Thus my confusion.
A wiki for the manual would be okay, but I don't see a problem with the serial format. As I see it the main purpose of the manual is to inform the user about the capabilities of the editor and provide general orientation. I at least would read it from front to back and then use tutorials to figure out how to do specific tasks. Of course the manual would also be used to look up things from time to time. But a table of content will do that job.
OpenMW is a pretty complex program, isn't it? How many people will have the time to read a manual for it front-to-back and why should they bother if they're only going to use half its functionality either way?

Reading a manual to learn something seems kind of strange. How would you even do this? Either you optimize it for teaching (by putting definitions of technical terms upfront and put topics in an order in which they are building on each other) or you optimize it for searching and putting related topics close to each other. The two ways of doing this conflict – you cannot have both. Teaching groups before addition is a bad idea, but in a manual for algebra I'd definitely put groups first.
User avatar
Zini
Posts: 5538
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini »

We are getting dangerously deep into nitpicking territory here with the question what a tutorial is.
OpenMW is a pretty complex program, isn't it? How many people will have the time to read a manual for it front-to-back and why should they bother if they're only going to use half its functionality either way?
Well, I do. And I am sure for a lot of more technical minded people that is a common habit. Of course there are also a lot of people who don't do that. My point was that people approach these things differently, so tailoring our documentation to a specific style of learning is a bad idea.
HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish »

The distinction doesn't really matter here, I am not planning to write any tutorials for the manual beyond that. What Ogre does is way past what I have envisioned. As for book VS wiki, I don't really care either, Pandoc can convert reStructuredText to wiki markup. We can really export to anything, I have even tried out making a manpage of all things, and even that works great. I think I'll put it all in a public repository on GitLab later, then you can read the rendered result online as I push it. If you like what it turns into we can move the repository to become part of the project on GitHub.
Antsan wrote:I wanted to use a Common Lisp library for generating docbook-xml (because xml itself is horribly verbose), but there was a bug in docbook-xml where ampersands weren't escaped correctly in the transformation from docbook-xml to TeX, at least not when they were the only thing in a title, which is really annoying when you're trying to write a section explaining the '&' operator.
I'll have a look at reStructuredText. Looks good so far, although I really liked the explicit document structure docbook-xml allows for. Having a subsection inside a supersection just seems more reasonable than having it under the supersection.
Pandoc can ronvert reST to DocBook. Couldn't you run sed on the LaTeX output from DocBook before compiling to PDF? Yeah, it's a hack, but if it gets the job done.

Anyway, I decided to look up DocBook and I cam across this book review on O'Reilley's website, emphasis is mine :D
It's certainly the definitive guide to constructing a DTD and the base set of tags, but it really lacks one major thing: taking the user through creating and formatting a document. It's all nice and well to understand all the tag inheritance and syntax options, but if you can't actually write and format documents to see how the various tags look, it's really not a "definitive guide". If you could add just one working example of creating and formatting a plaintext and PDF document, it would dramatically improve this book.
http://shop.oreilly.com/product/9780596 ... owerReview
Antsan
Posts: 47
Joined: 13 Mar 2014, 11:15

Re: Manual & Icons

Post by Antsan »

Zini wrote:We are getting dangerously deep into nitpicking territory here with the question what a tutorial is.
OpenMW is a pretty complex program, isn't it? How many people will have the time to read a manual for it front-to-back and why should they bother if they're only going to use half its functionality either way?
Well, I do. And I am sure for a lot of more technical minded people that is a common habit. Of course there are also a lot of people who don't do that. My point was that people approach these things differently, so tailoring our documentation to a specific style of learning is a bad idea.
I wasn't aware the manual was intended for learning. I expected it to be for reference.
HiPhish wrote:Couldn't you run sed on the LaTeX output from DocBook before compiling to PDF? Yeah, it's a hack, but if it gets the job done.
I'm not sure whether that would work. '&' is probably a special character for a reason – who tells me I'm not escaping some actually needed special characters?
HiPhish wrote:Pandoc can ronvert reST to DocBook.
Don't care. When I choose to use reST I can convert to HTML or PDF directly. Taking a detour over DocBook would provide no benefit as far as I can tell. I only took the detour over DocBook before because there is a Common Lisp library for converting S-expressions (Lisp syntax) to XML with proper escaping already (I checked that the incorrect escaping didn't happen here – the resulting XML had everything escaped as it should be).
Post Reply