Decent helpfiles and FAQ planned for 1.6.0 or later?

[Guckytos]

Hi Guys,

I was just again stumbling over a newbie asking questions about weird looking Celestia on his system, which as usual were caused by outdated or Microsoft drivers.

And then I looked again at what Celestia offers and came to the same conclusion as usual. If it wasn't there at all there would be nearly no difference.

With Celestia getting more and more features and graphical displays and more options for STCs and SSCs and all data formats, let alone speaking of celestia.cfg, I think it is high time to think about developing a better help!
Even Microsoft products have a better help

I have heard that it is hard to develop this for the different OS, but at least when Celestia switches to Qt it should be done. And some decent basic files be integrated and presented in an optical and organized way.
These files could then also be translated to different languages.

FAQ:
For 1.6.0 I would suggest, that at least a compiled FAQ (as an HTML that calls for the standard browser of the OS) be integrated. And the first point in this FAQ should be the driver problems. Okay, this point is mostly for Windows users, but those have the most problems with drivers.

Yes, most people don't read big manuals these days, but if you have a problem and the software offers und help a "FAQ" you normally take a look there. This would help people a lot.

The FAQ(s) that we already have could be used to create the "onboard" FAQ.

Helpfiles:
Here I would think that under the "Help" menu option you would get a bit more than just the keyboard layout.
I would suggest some of the following in no order (always in short form):

• A description of the basic of Celestia (scientific, 3D, ...)
• description of the basic handling/use ("Enter/name/Enter"-method, ...)
• description of the different filetypes
• addon installation
• the different layers that can be blended in and out
• astronomical basics (ecliptic, equatorial plane; ...)
• ...

I see files like these only as a starting point, that don't need to go really deep into the matter, but to give the user a general idea. There could then be added links to the Wiki, the forum, the ML and so on.

But to just say: Here's a soft, it's great, and yeah, if you want to know something about how to use it or how it works go into the net and find the wiki and read there or the forum is a bit arrogant.

So, my 2 cents.

What do YOU think about this idea? And yes I am participating in such an effort.

Best regards,

Guckytos

[chris]

Hi Guys,

I was just again stumbling over a newbie asking questions about weird looking Celestia on his system, which as usual were caused by outdated or Microsoft drivers.

And then I looked again at what Celestia offers and came to the same conclusion as usual. If it wasn't there at all there would be nearly no difference.

With Celestia getting more and more features and graphical displays and more options for STCs and SSCs and all data formats, let alone speaking of celestia.cfg, I think it is high time to think about developing a better help!
Even Microsoft products have a better help

I have heard that it is hard to develop this for the different OS, but at least when Celestia switches to Qt it should be done. And some decent basic files be integrated and presented in an optical and organized way.
These files could then also be translated to different languages.

FAQ:
For 1.6.0 I would suggest, that at least a compiled FAQ (as an HTML that calls for the standard browser of the OS) be integrated. And the first point in this FAQ should be the driver problems. Okay, this point is mostly for Windows users, but those have the most problems with drivers.

Yes, most people don't read big manuals these days, but if you have a problem and the software offers und help a "FAQ" you normally take a look there. This would help people a lot.

The FAQ(s) that we already have could be used to create the "onboard" FAQ.

Helpfiles:
Here I would think that under the "Help" menu option you would get a bit more than just the keyboard layout.
I would suggest some of the following in no order (always in short form):

• A description of the basic of Celestia (scientific, 3D, ...)
• description of the basic handling/use ("Enter/name/Enter"-method, ...)
• description of the different filetypes
• addon installation
• the different layers that can be blended in and out
• astronomical basics (ecliptic, equatorial plane; ...)
• ...

I see files like these only as a starting point, that don't need to go really deep into the matter, but to give the user a general idea. There could then be added links to the Wiki, the forum, the ML and so on.

But to just say: Here's a soft, it's great, and yeah, if you want to know something about how to use it or how it works go into the net and find the wiki and read there or the forum is a bit arrogant.

So, my 2 cents.

What do YOU think about this idea? And yes I am participating in such an effort.

I was away climbing when this message was posted and just now noticed. I am in complete agreement that we need to significantly revamp Celestia's help system with some basic and easy-to-find documentation.

Probably the most important thing to have is a basic introduction to using Celestia via the keyboard and mouse. Basic selection, time control, and camera movement would be covered. The current FAQ should be updated and included with the distribution so that it's as easy as possible to find--it's simple to add it to the help menu. The most common questions (which usually involve graphics drivers) could even be duplicated in the README as well.

So, I'd propose the following for 1.6.0:
- Update the FAQ, include it with the basic package, and make it accessible via the Help menu
- Update the README, add some of the most common FAQ items
- Create a basic intro to controlling Celestia via the keyboard and mouse, and make this file accessible via the Help menu

Longer term:
- Create an astronomical concepts guide (can we borrow from KStars?)
- Create an add-on installation guide (but after 1.6.0, I'd like to drastically simplify the add-on installation process)
- Create a guide for add-on makers. I envision two parts:
- A comprehensive reference guide
- A 'cookbook'--a friendly introduction to add-on creation that is example-driven

Does this match with your ideas?

--Chris

[rthorvald]

So, I'd propose the following for 1.6.0:
- Update the FAQ, include it with the basic package, and make it accessible via the Help menu
- Update the README, add some of the most common FAQ items
- Create a basic intro to controlling Celestia via the keyboard and mouse, and make this file accessible via the Help menu

I suggest you drop the ReadMe format in the Help Menu, use HTML instead, and put all of the above there, divided in sections. That is easier to use, allows illustrations and links, and is simple to extend. Add a basic outline of how to install add-ons, too, perhaps, even in the first version. I?d be willing to produce and maintain this if someone else takes responsibility for the manuscript.

- rthorvald

[chris]

So, I'd propose the following for 1.6.0:
- Update the FAQ, include it with the basic package, and make it accessible via the Help menu
- Update the README, add some of the most common FAQ items
- Create a basic intro to controlling Celestia via the keyboard and mouse, and make this file accessible via the Help menu

I suggest you drop the ReadMe format in the Help Menu, use HTML instead, and put all of the above there, divided in sections. That is easier to use, allows illustrations and links, and is simple to extend. Add a basic outline of how to install add-ons, too, perhaps, even in the first version. I?d be willing to produce and maintain this if someone else takes responsibility for the manuscript.

I agree that switching to HTML for the README is good idea. Controls.txt could also be converted to an HTML file in order to improve readability.

--Chris

[Fenerit]

Not only, but it will possible to cut and merge important articles from the this forum without rewrite again the same things...

[ElChristou]

Then a pdf would be IMHO better...

[rthorvald]

Then a pdf would be IMHO better...

No, PDF is not good for several reasons:

1. Copying from it is clumsy
2. Every time you update it, you must go over all the links in it anew.

HTML is better - also because it is very simple to exchange data with the Celestia Wiki, but first of all because it is a format everybody can read easily, and editing it is simpler than editing a PDF. Example, i would produce the PDF in my favourite layout software - which is quarkxpress. The next guy would use Word. The next one perhaps do not have neither of those... All you need to edit the html file is a text editor.

- rthorvald

PS: if there is some agreement here, i will create a test template for this, using what we have now. But i?d still want someone else to take care of the manuscript.

[chris]

Then a pdf would be IMHO better...

No, PDF is not good for several reasons:

1. Copying from it is clumsy
2. Every time you update it, you must go over all the links in it anew.

HTML is better - also because it is very simple to exchange data with the Celestia Wiki, but first of all because it is a format everybody can read easily, and editing it is simpler than editing a PDF. Example, i would produce the PDF in my favourite layout software - which is quarkxpress. The next guy would use Word. The next one perhaps do not have neither of those... All you need to edit the html file is a text editor.

- rthorvald

PS: if there is some agreement here, i will create a test template for this, using what we have now. But i?d still want someone else to take care of the manuscript.

I agree that HTML should be preferred over PDF. Also, since HTML is a text format, it's easier to track changes do the document in SVN.

--Chris

[Guckytos]

Then a pdf would be IMHO better...

No, PDF is not good for several reasons:

1. Copying from it is clumsy
2. Every time you update it, you must go over all the links in it anew.

HTML is better - also because it is very simple to exchange data with the Celestia Wiki, but first of all because it is a format everybody can read easily, and editing it is simpler than editing a PDF. Example, i would produce the PDF in my favourite layout software - which is quarkxpress. The next guy would use Word. The next one perhaps do not have neither of those... All you need to edit the html file is a text editor.

- rthorvald

PS: if there is some agreement here, i will create a test template for this, using what we have now. But i?d still want someone else to take care of the manuscript.

I agree that HTML should be preferred over PDF. Also, since HTML is a text format, it's easier to track changes do the document in SVN.

--Chris

I also agee that it should be HTML (at least for the moment), same arguments as above. But later on (Qt Celestia) perhaps it would be possible to go for an XML-File that is presented by QT in something that resembles "normal" Windows (I only have that as reference) helpfiles?
XML would be as easy or even easier to maintain as HTML and is also editable through a normal text editor. And probably better for translation into other languages. That is also an important point I think.

Template sounds good, that would be very welcome.

Ok, I will tackle the FAQ and try to cook something up, if someone wants to join me there, you are welcome. I will start by taking what's here on the forum and then think about it.

So, I'd propose the following for 1.6.0:
- Update the FAQ, include it with the basic package, and make it accessible via the Help menu
- Update the README, add some of the most common FAQ items
- Create a basic intro to controlling Celestia via the keyboard and mouse, and make this file accessible via the Help menu

I agree with Chris here. These are the first item that we should tackle. If we have spare time left, before 1.6.0 comes out, we can still add more documentation.

Regards,

Guckytos

[Guckytos]

Okay,

I have compiled a first draft version of the FAQ pages.

Edit: I have a second draft, with more info on Vista issues Celestia_FAQ_Draft_2.pdf

If you have any comments or suggestions for questions to add, please feel free to post them here.

Regards,

Guckytos

[ElChristou]

I was doing some HD cleaning this morning and came over an old html Readme version I did in 2006. I've updated it and here it is:

README.html.zip

If such doc is used, the doc AUTHORS should also be in html to have the mail addresses clikable...

[rthorvald]

I have a preliminary model for the Help ready.
It is designed with the following in mind:

1. Both the output and the code is to optimized for readability.
2. It must work on any browser, both with and without css and javascript
3. It should be as simple as in any way possible, both to navigate and to edit
4. The design must be clean and uncluttered

... For these reasons, there are almost no design in it - it is a flat, single-page document (to facilitate in-browser Search), with very toned-down colors / lay-out, and with almost no graphics. Also, it uses the same logo, colors, fonts and navigation model as the shatters.net Celestia website, to keep "in style".

For now, i show the model with the existing Celestia Help in place, together with a suggestion for the navigational sections, and the first entries in Guckytos?FAQ as an example of what it will look like.

I will not add any more content to it until Guckytos has finalized the manuscript and have had it approved by Chris and the other devs, since that would just entail a lot of re-editing.

So, while you guys work on the manuscript, i will only take suggestions for how to make the layout work better.
You can see it here:
http://www.celestialmatters.org/users/rthorvald/guide/

- rthorvald

[Cham]

Runar,

your document is very nice. But could you make the left column narrower ? I think it's just a bit too large. The upper-left Celestia icon could be a bit smaller in this case (ok, I know that you want consistency with the title at the right...).

[ElChristou]

What will be the final use of such doc? Online or in the package?

[rthorvald]

What will be the final use of such doc? Online or in the package?

It would replace the contents of the Help Menu in Celestia 1.6.

- rthorvald

[rthorvald]

Runar,

your document is very nice. But could you make the left column narrower ? I think it's just a bit too large. The upper-left Celestia icon could be a bit smaller in this case (ok, I know that you want consistency with the title at the right...).

Cham,
Click Celestia Controls > Keyboard Controls. See the menu folding out.
I have no way of knowing how long those titles will become, or how many nested levels may appear. So, making it narrower may cause formatting problems at a later stage. I?d prefer having it wider.

- rthorvald

[Cham]

It would replace the contents of the Help Menu in Celestia 1.6.

Then I strongly suggest to use non-serif fonts only. The text with serif is usefull for a printed document, but it's a bit hard to read on a screen. The font used for the extended bold text is a bit hard on my eyes.

Also, the red strings (ex :

# IgnoreGLExtensions [ "GL_ARB_vertex_program" ]

) is very hard to see.

[rthorvald]

I strongly suggest to use non-serif fonts only. The text with serif is usefull for a printed document, but it's a bit hard to read on a screen. The font used for the extended bold text is a bit hard on my eyes.
Also, the red strings (ex :

# IgnoreGLExtensions [ "GL_ARB_vertex_program" ]

) is very hard to see.

I?d like more opinions on this.
Perhaps the monospace font should be bigger, i see that. But the serif for keyboard shortcuts helps to accentuate the shapes of the small key symbols.

- rthorvald

[Cham]

[But the serif for keyboard shortcuts helps to accentuate the shapes of the small key symbols.

I don't see how. Using bold fonts with the dark blue color should be enough, for the clarity on screen. Try it without any serif.

[chris]

I strongly suggest to use non-serif fonts only. The text with serif is usefull for a printed document, but it's a bit hard to read on a screen. The font used for the extended bold text is a bit hard on my eyes.
Also, the red strings (ex :

# IgnoreGLExtensions [ "GL_ARB_vertex_program" ]

) is very hard to see.

I?d like more opinions on this.
Perhaps the monospace font should be bigger, i see that. But the serif for keyboard shortcuts helps to accentuate the shapes of the small key symbols.

I don't have any trouble reading the monospaced strings on my Windows system. I don't think that you should use a sans serif font for these.

As for the keyboard command font, sans serif seems like it would look better, but don't switch the font if it would obscure the shape of some of the symbols.

--Chris