Serious question/discussion about OO user manual (OO wiki)

[qwertyasdf]

Hello all,

I have not posted much, so maybe my post won't have much of a weight around here, don't know. Worth a shot anyway.
Just a mild intro: I am a computer specialist, having worked with them since late 80s. Today I teach at a university and occasionally write a script or check someone else's code to make sure it is done well. I teach complex stuff, not just computer science. This fact comes in handy for what I want to discuss here. BTW, as a teacher I get top marks - so much so that students take my courses only because they KNOW they will learn, no matter what. The courses in my school are quite difficult, to say the least. I think that the only reason students like my teaching style is the fact that I skip NOTHING when I teach. Not one stone is left unturned, not one thing is left poorly explained. Everything that is new to them, I explain thoroughly, give plenty of examples and students learn. It still does not make it easy, but I can go home satisfied that there was nothing more I could have done to make them learn faster or better.

Now, I have been using OpenOffice, on and off, for a few years. At first, it was just a way to avoid that other company with, hm, "similar product" for lack of a better description.

Lately, however, I wanted to use OO for more serious project - a book. From what I gather, this may be pushing the envelope a bit, but should not be impossible. There were few things that I liked immediately, and those keep me interested in OO despite the unsurmountable problems which I will come to very soon. For instance, the fact that text files are stored as text, not as binary code, is golden. I actually did have files which got corrupted (OO becomes unstable when writer files go back and forth between OO and MS word, especially when there are comments involved - that's like a death sentence to the file), but I managed to save them all but uncompressing them and then editing out the corrupt parts manually and compressing them back into the OO format. It was not even that difficult or time-consuming.

---------------------------START FROM HERE IF YOU DON'T HAVE THE TIME TO READ THE ABOVE INTRO---------------------------------

(Note: all the bold text is quoted directly from OO wiki.)

However, and this is the reason I am writing here, when it comes to LEARNING OpenOffice, even essential stuff such as formatting, styles, templates, OO becomes useless. Absolutely and utterly USELESS.
Why?
Because it is all looked up inside some programmer's mind. Whoever wrote the code for those tools, seems to have done a decent job of writing that code. Now, if HOW the code works is not shared with the world, it will take an eternity to figure out something that should be a matter of few minutes of careful reading. Most people like myself don't have that kind of time. The only thing that OO has going for it in that respect is that fact that MS or any other company is equally bad at writing documentation. So, the choice is between two of the same, and I'd rather stick with OO.

Here is an example of what I mean. I was looking for a definition of a "TEMPLATE" in open office and I found this, in OO wiki:

"Document Templates
Templates provide a quick way to create new documents form scratch. They define both the logical structure and appearance."

That's how the explanation starts. Read it carefully again. Definition of anything has to start with "Templates ARE..." and then fill in the blanks. If it doesn't start with "This IS..." then, it is not a definition. That part is missing. Are templates a tool? Or a method? A collection of tools? A workflow? A collection of workflows, tools and whatnots? We don't know that at all.
OK, lets read further:

Under the heading "Document Templates" there is that little explanation and then a link: BACKGROUND INFO. "Woo-hoo!", I am thinking. I may just find out who, how and why they wrote that tool! I click on the link, hoping for some low-level, insider info. I get this:

Temnplates - Personas
Elliot, Med Student

Elliot is a student of the Medical faculty of Charles University in Hradec Králové. Living at the student dorm, she shares her room with another student, Carla. Elliot studies othorhinolaryngology. While studying, she also volunteers for red cross.

And that's that. My "low-level coding info" or whatever I was hoping for. I can't say it is irrelevant, because it is so utterly wrong, that it is not even funny.

OK, let's move on. Still excited about templates:

I find a link on the left side - TEMPLATES. I click on it and I get a whole page of various templates. This page:
https://templates.openoffice.org/

Obviously, no explanation, just templates. Use them, but don't try to get smart now. We don't want you to KNOW what you are doing.

OK, let's try the built-in help file, in OO itself. Find "templates" in it and the first thing should be the definition of a template. Here's what I got:

Agenda Wizard
Starts the wizard to help you create an agenda template. You can use an agenda to specify discussion topics for conferences and meetings.

Useless. All other attempts to understand templates go about the same. Vague explanations on how to use them, zero definitions of WHAT THEY ARE.

You get the picture.

Same happened when I tried to understand how styles work, what and how the cryptic "default style" was, and how that worked and the hierarchy of styles and so on... No decent explanation ANYWHERE. The only thing one gets is an occasional selfless explanation from one of the users here, which as much as it is appreciated is not the way any software should be supported. My motto is: do it once, and do it right. OO has been supported multiple times, and never right. Again, I appreciate the help here on these forums, but it is also an unnecessary burden on those who help, when they could be writing the manual and so on.

We do need Open Office, unless we want to be voluntary slaves to companies such as MS. But, this is not the way to do it. OO will linger in the neverland of unexisting explanations and manuals, and will forever be banished to the select few who have grown up with it and therefore know it inside and out while others try it and abandon it disgusted by its lack of usefulness (What you can't use, is useless, right?).

Let's get that manual going. Heck, I will even donate a bit of my own time for the cause, but not by guesswork. The first and most important rule of OO should be this:
1. Whoever writes or wrote a tool MUST submit a detailed explanation for it - not just how to use it, but most importantly: HOW IT WORKS. The code itself MUST include all the pertinent comments in it, must be clean, and must be explained. Same with updates and versions. Having seen much of computer code in my life, I doubt that this is how OO was created, but then again, I may be wrong. Programmers are notoriously difficult when it comes to sharing what is locked up in their mind. They think that if something works, that's all that matters. Well, look how far that got Boeing with computer code that stayed unexplained. It brought down two airplanes, and probably started the end of once great company. Call me paranoid, but I don't want my future with MS in it.

Am I reaching for the stars, or do you guys think I am onto something? Most of you have been around these boards way longer than me, so any input is appreciated. If I conclude that I am way off base here, and am looking for something that would never happen, well, then I'll do as everyone else: give it a shot, and then move onto an application that works and is well documented.
Or we could make OO work and be well documented, Our choice.

[qwertyasdf]

I have indicated which materials i have used:

- OO wiki
- OO help within the application itself.
- The list of links on the left side of the same page on OO wiki

Thanks for the link at openoffice guides (it is for an old version though, like 9 years old). I have opened the page about templates, the 10th chapter, and was immediately discouraged. Here is the first sentence:

"A template is a model that you use to create other documents."

A "model" of what? That's a self-referring definition.

- Where is USA?
- Near Canada.
- OK, where is Canada?
- Near the USA.
- OK, where are both the USA and Canada???
- Near each other.

You get the picture.

The documentation has no meaningful (beyond self-referencing definition) explanation of what is a template.

Maybe templates are unimportant and I should give up on them. Or maybe people don't care to read important information before they use something, don't know. But reading a few posts around here, I get the impression that OO is slowly dying, and cannot help but feel that this terrible excuse for documentation is one of the main reasons. Ease of use depends on documentation. Undocumented features are as good as non-existing ones. They are waporvare, forever locked in some programmers mind, and never really shared with anyone. OK, few persistent experimenters may get to the bottom of it, but most people don't have that kind of time. What can be explained in a sentence or two, SHOULD be explained in a sentence or two.

[robleyd]

If you believe you can contribute to the documentation, you might wish to join the Documentation Mailing List and offer your services.

[qwertyasdf]

I'd need to know the application first to be able to contribute.

[robleyd]

You have thoughts on how the documentation is lacking and how it might be improved; you could pass that on.

Note that this forum is a user forum with volunteer users providing assistance - we don't have any control over the actual development or documentation of the project, nor do those involved directly with the project visit here, to our knowledge. So the only way you can have any direct impact is to talk with those who are involved in the project.

[RusselB]

You have stated that you read through the OO Wiki, but did not indicate which OO Wiki you read. There is more than one. Please provide the actual linked website address so that we can know that we're trying to deal with the same information basis.
As to Templates, there are several already made in order to make creating a document of a specific set-up easier.
Eg: There may be a template for a Living Will, which is going to be different from a template for a Resume. Both are Writer style documents and could be done without a template, but having a template makes it easier to have the same type of information in the same area as what you might expect.
There is, by no means, anything that says you have to use a template, and that's if there's a template already made that fits your requirements.

[Zizi64]

"A template is a model that you use to create other documents."

A "model" of what? That's a self-referring definition.

My definition of a "TEMPLATE":
A template is a document with a special URL behavior and some predefined formatting properties (styles) and/or contents.

I know that you you will ask:

What is a "document"?
What is the "special behavior"
What is the URL?
What means the "predefined"?
What are the "styles"?

[Lupp]

And another version:
-0- A template roughly is what the word is suggesting for anybody speaking English.

Beyond that there are a few things to know before starting to use templates efficiently.

-1- Technically a template is a document of the class it is made for (a Writer document e.g. for creating Writer documents).

-2- Intentionally it is made to ease the creation of documents for specific purposes. It is expected to provide style settings and/or fix preset content and/or hints how to use/fill it. (Probably even user scripts.)
(Concerning what is called "style elements" above an understanding of the usage of styles depending on the style families and the different document classes is indispensable. It cannot be teached here in detail.)

-3- Technically again a template is marked as one by the usage of a different filname extension (.ott e.g. instead of .odt). Best save a new template as one by choosing the template variant in the 'Save As...' dialog.

-4- Technically again there is provided a specialized tool for managing templates. You find it by going >File>New>Templates and Documents.
(Yes. This is misleading. There should be a way via >Tools. On the other hand you also can select a template to use for your next new document there.)

-5- To learn about the usage of the template manager you can read in the mentioned guide without knowing where Canada is.
(If you want to use OpenOffice derivatives in the long run you should consider that there already developed -and continue to develop- differences between AOO and LibreOffice, unfortunately many of them concerning the UI. We cannot go into more detail therefore without writing -at -least- two versions. LibO seems to be the more promising branch for future use.)

-6- (Don't miss to study -7-!) You can also decide to (partly or generally) abstain from using the template manager and instead create (e.g.) a subtree in your file system where you keep your templates together with the kinds of documents created from them. If you simply rename an .odt (e.g.) document intended to work as a template to .ott and "open" it without additional precautions using the shortcut your OS provides (doubleclick in the file manager on Win e.g.) it will not be opened for editing, but an "Untitled' new document will be derived from it.

-7- (Afaik) There is a valuable (but probably sometimes dangerous) feature concerning managed templates:
Only usage of managed templates provides this useful service: Info what template was used at what date-time to create a document is saved with the document. If you open such a document later your Office app will look for the template, and if it is found in place, but was changed since the document's creation you are prompted for your decision whether or not the styles should be updated. (I don't know for sure if AOO and LibO still behave exactly the same way insofar.)

-8- Most likely there are lots of additional things about templates I don't know. But you may now know where to find the USA.

[John_Ha]

Your example of template is disingenuous as you quote only the first line of the manual and ignore the reset of the paragraph and the following nine pages all of which are dedicated to describing how to use templates. What do you expect? Everything in one short, easy to be understood by a three-year old, line? You will be disappointed as there is no more a "royal road" to OpenOffice than there is a royal road to maths - just work on your part.

You also do not seem to understand how definitions work. Definitions use analogies and synonyms, usually simpler than the defined word, where the definer hopes that the reader understands the simpler synonyms and so gets an appreciation of the word they do not understand. All definitions eventually recurse as there are only a finite number of words in any language.

Further you are confusing what something is with how something is used. If you want a programmer's definition of a what a Writer template is and how AOO handles it she will say:

A template is a standard .odt file which has a .ott qualifier. AOO opens it as a normal .odt file and disables the Save function

You now have your complete definition of what a template is. You can now do the work to understand what the implications of this are and how it can be used and you have everything you need. I suggest you will find reading Chapter 10 - Working with Templates in the manual to be a far quicker, easier and more reliable method.

[qwertyasdf]

Thanks for all the replies guys. The last post saying my example is "disingeuous" (another word for "dishonest") is a typical troll wrapped in nice phrasing. The Royal road to math starts with simple definitions. Yes, there will be many of them - one per subject or detail, but if you asked me what a floating point number was, I would not start by saying how to use it or how many digits it may have, or compare it to fixed point number.Everything else would be useless without knowing what a float IS first.
Same with templates. The definition in the same post is not bad at all, as it does help understand what templates are.
If you can't explain something in a simple way, you don't know it. People who know should be the ones who write OO user manual. And people who can't explain should stay away from writing manuals - they discourage new users of the software.
Again, thank you all for your input, it is much appreciated. (even the last, lightly trolling one)