Manual & Icons

[Okulo]

Well it is pretty obscure to me, I did use it about 12 years ago but saw no advantages of it. I am fairly sure 90% of computer users have never heard of it.

Neither did I before I worked on the manual, but that doesn't make LaTeX obscure or anything. Apparently it's used often enough to have a legitimate function.

those that did [contribute] have done nothing for a year, the chosen method is obviously not working.

The problem isn't LaTeX for me. That was simple enough to pick up and learn. The problem is mostly writing a manual for an unfinished project that is subject to change and not knowing much about how it's structured, its context in the final product or even the creator's vision for the future. Ironically it's the lack of documentation that stopped me from writing the manual. With all these other things going on in my life, I don't have much time to delve into the specifics of OpenCS, figure OpenMW's inner workings etc. I was writing a manual (and now newsposts) to "translate" the more complicated programming concepts to something everyone could understand.

What the manual needs is someone who is both familiar with OpenCS/OpenMW and knows how to explain it simply without using technical slang.

[psi29a]

What the manual needs is someone who is both familiar with OpenCS/OpenMW and knows how to explain it simply without using technical slang.

Zini, that's you buddy. You are both the vision holder, content creator and programmer of OpenCS.

I'll be honest, create a manual that I can read and use... and I'll create, for everyone, an Example-Suite.

I've never once used a mod in Morrowind, I've also never used the "The Elder Scrolls Construction Set". So I have no idea how 'bad' it can be.

Teach me how to use OpenCS.

[Zini]

who is both familiar with OpenCS/OpenMW

That's me alright.

and knows how to explain it simply without using technical slang.

This is definitely not me.


As mentioned before I am available to answer questions and explain things. But I won't get into writing the manual myself. Even if I had the time for that, it would be a bad idea. End user manuals I write usually suck.

[sirherrbatka]

@psi
we have a deal

[Tinker]

I have experience in writing manuals for unfinished and changing products, that is not the problem. Maybe it is me but I cannot work out how to use the current authoring system. Perhaps as I am an author I prefer to see words when I am writing and seeing code spread throughout is distracting but I cannot even get that far.

I am willing and able to help but not using the current system, is there something intrinsically wrong with using the wiki for the manual?

[sirherrbatka]

Maybe it is me but I cannot work out how to use the current authoring system.

Oh so that is the problem?

Latex is not obscure. At least not more obscure than wikipedia markup. And, what is more: you can edit it offline, manage those files with git without a problem and generate high-quality pdf files ready for print. If you have problem with authoring, just think that every commit you make is tracked in the git history.

[psi29a]

Not knowing about LaTeX, and how to use it, in a the documentation world is a reason on not to hire that person for the job. Our technical writers have a good working knowledge of it, however that isn't their job. Their job is to write good technical user manuals and API documentation.

Thankfully there are tools that allow for intermediate steps like Sphinx's autodoc function. It uses doctype and ReStructureText (RST) to generate the API documentation from your code and you can add static pages (with media) as well for user manuals. You can output to LaTeX which can then be used to make PDFs. It also supports output to ePub, html, you-name-it.

If you can make the manual in RST (a variant of markdown), then you can have sphinx dump it to whatever format you want. I would say it is easier to work with than straight LaTeX itself, but you are more or less straight-jacketed into Sphinx's layout.

[Tinker]

Latex in itself is not a problem, I wrote a book using it about 10 years ago, but to be honest it would have been easier to use any word processor to do it and the end result would have been the same. I can see a use for it in a commercial environment where dozens of people, including coders, would have some sort of input and would prefer to work with a system they were familiar with. I am not looking for a job, I have no need to work, and I am offering my help to a project that I think is great but I also want to work in a manner that I find comfortable. Fiddling around with what to me are obscure processes is not comfortable.

I have not found out how to edit files online or offline without resorting to cut'n'paste, managing files with git may be simple for those who do it every day but I find it more than obscure, more of a black hole. I have a very basic grasp of coding but have not actually written any software for 40 years, I can fiddle around with scripts in mods somewhat but I know nothing of modern coding environments such as git, and would prefer to leave that for coders.

I can follow the reasoning behind producing pdf files even though they are the spawn of satan, the worst possible solution for publications which has become a de facto standard, but why anyone would want to print things beats me, run it in a browser window or on a tablet, convert it to epub if you want, anything that you can add bookmarks to or hyperlink to an index and contents page, but paper.

If you insist that this is the way to write a manual then I withdraw my offer to help.

[psi29a]

Tinker: That is what I'm suggesting.

Perhaps LaTeX isn't the best for people wanting to jump right in and help documenting things. Maybe another intermediate step is necessary, like ReStructuredText or MarkDown which can be converted to LaTeX is a better idea?

For most of the opensource and all (work) closed-source projects I work on, I do the above.

As a matter of fact, I'm doing it right now for Twisted's Ldaptor (OpenLDAP library for Twisted). I'm converting existing xml/docbook documentation to RST. From there I export (via readthedocs.com) to HTML, LaTeX, ePub and PDF.

[sirherrbatka]

I wrote a book using it about 10 years ago, but to be honest it would have been easier to use any word processor to do it and the end result would have been the same.

Actually i learned latex after discovering what a pain in the ass is creating a large document using a word processor. Even 40 pages is enough to make this extreamly annoying. And as a end resoult… well the last time i checked latex was still giving better looking doucments.

but that is offtopic i guess.