Manual & Icons

Involved development of the OpenMW construction set.
ven
Posts: 8
Joined: 07 Apr 2015, 03:38

Re: Manual & Icons

Post by ven » 04 Feb 2016, 23:22

HiPhish wrote: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.
I had 0 experience with the CS. I did the ring tutorial with no problems. Well written, and easy to follow. It took me about 15mins but I was also talking on the phone at the time. Thank you very much! This was exactly the type of thing I was looking for to ease me into the CS.

HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish » 05 Feb 2016, 00:22

10 to 15 minutes was what I would have expected as well.

EDIT: Repository is up
https://gitlab.com/HiPhish/OpenMW-CS-manual
Click Files in the side-bar to the left and then click manual.rst to see the manual rendered directly in the browser. I won't be updating the Dropbox link anymore.
Antsan wrote:I wasn't aware the manual was intended for learning. I expected it to be for reference.
It can be both. Some people learn better by reading through everything and then actually doing work. When I learned C I basically read K&R C from cover to cover. When I learned Vim I read only the first few chapters of Practical Vim and then picked content as I saw fit. Some people also like to skim the entire thing and then later read in depth as the need arises.

spitzz
Posts: 1
Joined: 04 Feb 2016, 17:51

Re: Manual & Icons

Post by spitzz » 05 Feb 2016, 08:20

Hi
First off, thanks for the tutorial.

I followed the steps ok but got a bit lost at the effects table. I assume that is the magic effects table? It Was the only one I could find. Anyway I eventually found where I could add the effects record. When I checked in game I got this error in the console.
"Error: failed to create manual cell ref for ring_night_vision (unknown ID)"

No icons were visible either in the object table where I selected the ring.

I'm using linux ubuntu 14.04 lts 64 bit

Any ideas? thanks

User avatar
Zini
Posts: 5134
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini » 05 Feb 2016, 10:22

I don't insist on the wiki format (especially if we can move the document to the wiki anyway). But can we have it in the official OpenMW repository, please? Spreading out stuff all over the internet doesn't sound like a good idea.
In manual/opencs-tutorials/ maybe?

User avatar
psi29a
Posts: 3452
Joined: 29 Sep 2011, 10:13
Github profile: https://github.com/psi29a/
Contact:

Re: Manual & Icons

Post by psi29a » 05 Feb 2016, 10:42

This please!

I'm comfortable with ReST format which can be used by any number of programs to translate it to pdf/latex/html... for example: Sphinx/Doxygen combination and we can use readthedocs.com to host the tutorials and manuals. RTD uses sphinx to read in the ReST and produces documentation for use on their site, free of course.

I use this for many projects.

HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish » 05 Feb 2016, 11:37

Zini wrote:...
Sure, I just uploaded it to GitLab because I am not part of the OpenMW organisation and I wanted to upload it somewhere. I figured on GitLab it would have a lower chance of being stumbled on by a random derp who would ignore the unofficial part and run with it like it was the real thing. We have seen how someone's experimental multiplayer branch somehow turned into "ZOMG Morrowind is getting multiplayer".

If you want to add it as an official OpenMW project I would recommend a separate repository since the manual doesn't use anything from the OpenMW source code. It reduces commit noise, developers don't care about documentations commits and writers don't care about code commits.
spitzz wrote:...
You're right, it's Magic Effects, fixed it. As for your other problems, OpenMW CS is still unfinished software, there will be problems. I try to write the manual as if there were no issues, there is no point in documenting issues that will be fixed by the time 1.0 hits.

User avatar
psi29a
Posts: 3452
Joined: 29 Sep 2011, 10:13
Github profile: https://github.com/psi29a/
Contact:

Re: Manual & Icons

Post by psi29a » 05 Feb 2016, 13:18

What you are doing is wonderful and please keep doing it! :)

Don't take what I have to say below as personal, but I have to comment on it because it simply isn't true.
HiPhish wrote: Sure, I just uploaded it to GitLab because I am not part of the OpenMW organisation and I wanted to upload it somewhere.
You don't have to be part of the OpenMW "organization" to create a pull request or create an issue or talk about stuff on github. You just create a fork, checkout the code, commit your documentation, then create a pull request, and off you go!
HiPhish wrote:If you want to add it as an official OpenMW project I would recommend a separate repository since the manual doesn't use anything from the OpenMW source code. It reduces commit noise, developers don't care about documentations commits and writers don't care about code commits.
I'm sorry, but I don't know where you are coming from with this. To suggest that developers don't care about documentation commits is frankly bullshit. They are the best individuals to verify that what is written is correct, a great peer-review group.

It is true that technical-writers (there are two on my team at the office) aren't overly concerned about the software development process, they do work together with us to make sure the documentation is accurate and as a result is it best to make sure that it stays in the repo itself. Documentation/manuals/tutorials, like code, are just text and are perfectly acceptable inside a repo.

That is why there are tools like sphinx that not only take tutorials, manuals and others written in documentation in conjunction with API documentation that is automatically generated from the source code. This just reinforces the necessity of having the documentation in the repo along with the code.

Examples:
https://github.com/Mindwerks/worldengine
https://worldengine.readthedocs.org/en/latest/
https://github.com/twisted/txmongo
https://txmongo.readthedocs.org/en/latest/
https://github.com/twisted/ldaptor
https://ldaptor.readthedocs.org/en/latest/

User avatar
Zini
Posts: 5134
Joined: 06 Aug 2011, 15:16

Re: Manual & Icons

Post by Zini » 05 Feb 2016, 13:36

Independently of how much developer care about documentation, having the documentation in a separate repository would be a nuisance regarding release and version handling. Please send a pull request to the official OpenMW repository. Too much noise is generally not a problem, not to mention that an occasional PR creates barely any noise at all.

HiPhish
Posts: 323
Joined: 02 Jul 2012, 08:36

Re: Manual & Icons

Post by HiPhish » 05 Feb 2016, 13:49

psi29a wrote:You don't have to be part of the OpenMW "organization" to create a pull request or create an issue or talk about stuff on github. You just create a fork, checkout the code, commit your documentation, then create a pull request, and off you go!
I had created some pull requests in the past, somehow I didn't think about it :?
HiPhish wrote:I'm sorry, but I don't know where you are coming from with this. To suggest that developers don't care about documentation commits is frankly bullshit. They are the best individuals to verify that what is written is correct, a great peer-review group.
My idea was the following: you are a developer, you sit down and there are 50 commits. But only 30 of those are actually affecting the source, the rest are just the manual and will never collide with the source code. So why would a developer have to sift through those to find the ones that could actually break code? It's the same the other way around. If you say that's not a real issue then I'll go ahead, I don't really care.
psi29a wrote:Don't take what I have to say below as personal, but I have to comment on it because it simply isn't true.
Don't worry, I'm not going to go into cardiac arrest because someone disagreed with me on the internet ;)

User avatar
psi29a
Posts: 3452
Joined: 29 Sep 2011, 10:13
Github profile: https://github.com/psi29a/
Contact:

Re: Manual & Icons

Post by psi29a » 05 Feb 2016, 14:05

HiPhish wrote:My idea was the following: you are a developer, you sit down and there are 50 commits. But only 30 of those are actually affecting the source, the rest are just the manual and will never collide with the source code. So why would a developer have to sift through those to find the ones that could actually break code? It's the same the other way around. If you say that's not a real issue then I'll go ahead, I don't really care.
You're not going to slow down development by committing documentation. Please add your name to the contributors list to while you're at it. ;)

I recommend ./docs/tutorials/ for now, unless someone else has a better location. This also includes images you use, that should be fine as well so long as the images aren't constantly changed.

Zini, you OK with images going into the repo? If not, then maybe a third-party image hosting service that you can direct link to in the documentation is best?

Post Reply

Who is online

Users browsing this forum: No registered users and 3 guests