OpenCS manual

[sirherrbatka]

Ok, so let's talk about opencs manual.

Before we can begin: a small confence. I love paper books. I love it, love it, love it!

That's why I want to not only create wikipedia manual, but also a simple, latex formated pdf. In fact I'm so focused on this perspective that I can lack any sane perspective on the subject. You are free to reject this concept on this basic.

My plan is to write it in the following style:
each chapter describes one specific feature of opencs:
each chapter starts with introduction explaining what this features does, next we have:
small dictionary for new terms,
basic usage,
advanced usage,
tips and tricks.

and that's it. I found that well structured text makes learning faster and more effective. And I love paper books, but you know this already.

I'm not the one to make videos, but those would be clearly extreamly usefull. The question is: should they be used directly inside the wikimanual, or rather contain semi-separate subproject ("turtorial point" or something).

Ideas? Opinions?

[HiPhish]

What are you going to write your manual with? Personally I use Doxygen for my own commercial project; Doxygen is usually used to document the source code (even though programers never do it), but it can be used to write user manuals as well. The neat thing for me is that it does both at the same time, so I can have one set of HTML documentation that contains both the user manual and the scripting reference.

To write a user manual in Doxygen use plain text files (txt), or if you want to make it clear they are inteded for Doxygen use Doxygen text files (basically plain text files with .dox as their extension). Each file has to start with /** and end with */ in order to parse the commands by oxygen. Anything outside such a comment block will be ignored. Programers usually start each line of the comment block with an asterisk, but that's not necessary. Here is an example:

/**
@mainpage
Welcome to the user manual and scripting reference for my awesome product.

@note Some images have been scaled down automatically in order to maintain the flow of text.

@section getting_started Getting started using this awesome product
Getting started is really simple. Just follw the instructions in this manual, and you'll be good to go.
*/

Doxygen can then export the result to HTML, LaTeX or whatever it is you want. i think using Doxygen is better than writing the manual in LaTeX directly, this way you still have the option to export it to HTML or whatever else there is. in fact, the result could be exported even in the native help format each OS individually.

The question is: should they be used directly inside the wikimanual, or rather contain semi-separate subproject ("turtorial point" or something).

You can't read and watch a video at the same time, so I think videos can be their own subproject. Sure, embedded videos would be nice, but let's keep it simple for now

[sirherrbatka]

Interesting I have never heared about it before. ofc you can also convert latex to the html without problem, and windows help manual files are IIRC compiled html files.

Still, we need wiki anyway. I also hope that I won't have to write everything on my own!

[HiPhish]

Do you really need to make a user manual act like a wiki? Wikis are great of encyclopedia style collections for information, but a user manual has to be written in sequence, like a novel. Each chapter of the manual builds on top of the others in a linear fashion, whereas in a wiki each article stands on its own with a ton of cross-references. That is why I recommended Doxygen, it will generate a nice HTML manual as well as LaTeX code for you and you have to write it only once. In fact, the entire website for Doxygen has been written in Doxygen:
http://www.stack.nl/~dimitri/doxygen/manual/index.html
If you want I can PM you the link to my manual as well, but it looks pretty similar, I didn't tweak the design. If you still want to have a wiki someone could write parser, the Doxygen documentation is written in Markdown, which is a fairly simple system. Doxygen can also output documentation in the XML format, then you can parse that with whatever you want and read it on our toaster if you want.
http://www.stack.nl/~dimitri/doxygen/ma ... lgenerator
http://www.stack.nl/~dimitri/doxygen/manual/output.html

you can also convert latex to the html without problem

Yeah, but I tend to avoid anything that generates something out of LaTeX like the plague (except for PDF of course). I'm a mathematician, so the two main highlights of LaTeX to me are its high quality readability and math support. I still have to see any system that can handle math that well. I even go so far as to actually write images in code rather than using an external drawing application, just to keep the quality and math support consistent.

[WeirdSexy]

Wiki version of the manual seems unnecessary/bad to me as well.

Videos could be useful, of course. I don't have a clear opinion on organization however. Embed them in the manual? Give direct links to them in the manual? Mention specific videos in the manual at all? Or simply say "for additional demonstrations in video format, visit YouTube"?

Seems like the cleanest thing to do would be demonstrate specific features with text + screenshots in the PDF manual and have videos that demonstrate the completion of simple mods or to suggest workflow for common modding tasks.

To be clear: I am not positively volunteering to make such videos. I've never been a modder.

[sirherrbatka]

Let's not forget about wikibooks. This also can be any solution.

[HiPhish]

Would a manual for one specific application really belong on Wikibooks?

[sirherrbatka]

I don't know.

I think that doxygen is the way to go. I must read how to write text with that.

[sirherrbatka]

@HiPhish

Can you recommend any decent turtorial on doxygen?

[HiPhish]

I'm afraid I don't know any good tutorial, most of what can be found is about commenting source code and how to format comment blocks, but not about writing manuals. The best so far has been the Doxygen documentation itself. If you need help ask me, I know how to use Doxygen. I use a separate text file for each chapter (for organization, you could also write it all in one file) and the order in which I tell Doxygen to parse them is the order of chapters. The first file is the main page, it is what the reader sees first:

/**
@mainpage
Welcome to the user manual.

@section toc Table of Contents
The user manual consist of the following pages:
- Page @ref overview gives you a rundown of all things relevant.
- Page @ref concept_of_mods explains the general idea behind mods in Morrowind.
- Page @ref getting_started jumps right into modding with a simple example.
*/

From there on each chapter looks somewhat like this (I like to define hyperlinks I'll use in the head of the document):

/**
[OpenMW]: https://openmw.org/en/
@page overview Overview

@section Preface
Thank you for choosing OpenCS, the modding tool for [OpenMW].

@section Setup
You get the idea...
*/

Doxygen uses a so called "doxyfile", it's a text file with information on what to parse and other settings, like a makefile. text is formatted using the Markdown syntax, which is really simple to learn and read, it's inspired by email formatting. Doxygen commands are written by either adding a backslash (\) like in LaTeX or an @ at the beginning. I find the @ easier to type on my keyboard, but it's all the same.

It would also be possible to include the source code documentation as well, but I'm not sure if that is a good idea. people reading the manual will want to know how to use OpenCS, not what it is made of. I'll leave that decision to the reast of the team, it can also be decided later, no need to waste thought on it now.