Decent helpfiles and FAQ planned for 1.6.0 or later?

[symaski62]

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

http://ati.amd.com/support/driver.HTML

ATI catalyst 8.9 driver

# IgnoreGLExtensions [ "GL_ARB_vertex_program" ] <= open & close

TEST

-------------------------------------------------------------------------------------

?h ! You may embed only 3 quotes within each other.

[t00fri]

...
http://ati.amd.com/support/driver.HTML

ATI catalyst 8.9 driver

# IgnoreGLExtensions [ "GL_ARB_vertex_program" ] <= open & close

TEST

-------------------------------------------------------------------------------------

?h ! You may embed only 3 quotes within each other.

How about trying to learn some VERY basic English. If this is too hard, just type your French text into the Babel Fish interface!

http://babelfish.yahoo.com/translate_txt

So we might get an idea about what you are hinting at...

If this is too hard, too, type your text in French. There are quite a few of us who are French or at least fluent in French (including myself)

Fridger

[Guckytos]

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

Hi Runar,

I appriciate your work on the template, but I have a few things to comment.

I don't think it is a good idea to use serif font in ANY document that is optimised for screen display. And it gets even worse, when using it in bold. Maybe I am just to tired at the moment, but I think it is not good to read (Section "Celestia Controls"). Either scale up the font size of the serif font or BETTER switch to sans serif font.

The Q and A for the FAQ section is not a bad idea, but I think if we have more points, using a numbering system for the Questions will be better.
The idea to use a completely different color for the lines of code in the config is good. The red isn't too bad, but could perhaps be darker. But is quite good readable on my CRT.

The size of the TOC can be adjusted, when the help is finished. At the moment it looks a bit big, but we have just started and don't know if we will have longer headings.

How do you plan to organise the FAQ sections?

One block with all questions at the top of the page (read from top)? And then from there links to the sections with repeat of the questions together with answers?

Regards,

Guckytos

Edit: I will try to put all the comments into the FAQ this weekend and then present an RC1

[rthorvald]

I don't think it is a good idea to use serif font in ANY document that is optimised for screen display.

Ok everyone is saying this but me, so i will try sans-serif for the next version, and we?ll see.

The Q and A for the FAQ section is not a bad idea, but I think if we have more points, using a numbering system for the Questions will be better.

Maybe both? I want the Qs and As to be very obvious so that the user can skim down the page quickly without losing track.

How do you plan to organise the FAQ sections?

I?ll leave that to you:

One block with all questions at the top of the page (read from top)? And then from there links to the sections with repeat of the questions together with answers?

That seems like a good idea, unless you can make titles short enough to fit in the foldout-menu.

- rthorvald

[symaski62]

viewtopic.php?f=3&t=12433

Celestia 1.5 pre3 et Celestia-ED 1.4.1 (Windows XP)

FAQ 1.4.1 et 1.5 pre3 => ATI Catalyst 8.4 version

#IgnoreGLExtensions [ "GL_ARB_vertex_program" ] <= to leave or to take ?!?

ctrl + V


---------------------------------------------------
? un handicap g?n?ral de 80% et il fait beaucoup d'efforts pour la communaut? et pour s'expimer, merci d'?tre compr?hensif.

with a general handicap of 80% and it makes much d' efforts for the community and s' expimer, thank you d' to be understanding.

[Cham]

? un handicap g?n?ral de 80% et il fait beaucoup d'efforts pour la communaut? et pour s'expimer, merci d'?tre compr?hensif.

with a general handicap of 80% and it makes much d' efforts for the community and s' expimer, thank you d' to be understanding.

Now, a long standing mystery is solved.

Toute ma sympathie, Symaski !

[ElChristou]

? un handicap g?n?ral de 80% et il fait beaucoup d'efforts pour la communaut? et pour s'expimer, merci d'?tre compr?hensif.

with a general handicap of 80% and it makes much d' efforts for the community and s' expimer, thank you d' to be understanding.

Now, a long standing mystery is solved.

Toute ma sympathie, Symaski !

Yes, but once more, there is no shame in having any kind of handicap; if people feel ok to stay in the community, they ought to tell us about their problem as soon as possible instead of waiting sarcasms or other kind of offending comments...
(Je traduis Sym? )

[rthorvald]

One block with all questions at the top of the page (read from top)? And then from there links to the sections with repeat of the questions together with answers?

I have put up a new version that suggests a neat solution for this. See http://www.celestialmatters.org/users/rthorvald/guide/
Only the first two faq items have any content, still.

This version uses javascript, but it degrades gracefully and is fully usable without.

Also, in this version: i have organized, formatted and put in all the other text files distributed with the program (contributors, getting started, licence).

- rthorvald

[Cham]

Very good work Runar.

I don't have any critics yet !

[Guckytos]

Hi Runar,

looks definitely better with the sans serif font.

It's become VERY neat, and I like it. I only think that the "Getting started" section needs a major makeover.

At the moment I am just waiting for some updates from Chris on the graphics section. Then the FAQ texts could be completely integrated and tested in actual Celestia builds.

But confess, you used ElChristou readme for all the rest of text in that page. This one is from 2006 so, it will need a whole makeover.

Regards,

Guckytos

EDIT: You forgot to mention the Motherlode documentation page

[Cham]

Now, is this doc supposed to replace the help window, in the application ? If so, what about the localisation (French version, etc...) ?

[rthorvald]

Now, is this doc supposed to replace the help window, in the application ? If so, what about the localisation (French version, etc...) ?

It will be easy to edit. Anyone with knowledge of the language in question will be able to do it in a text editor, without needing to touch any of the code.

- rthorvald

[rthorvald]

But confess, you used ElChristou readme for all the rest of text in that page.

No, everything comes straight off svn.

- rthorvald

[rthorvald]

EDIT: You forgot to mention the Motherlode documentation page

No, i didn?t. I am NOT editing the texts at all, apart from a few logical necessities (like removing the reference to an external document that has become part of the actual text), everything is exactly as it is in my latest Celestia build. So anything missing must be supplied via an "official" manuscript.

It must be so since anything else would cause versioning problems between us; you or someone must be the "official custodian" of the content, and i will just take whatever is supplied and format it.

A note to Cham?s question on translations:
When i get some time i will look into the possibility of creating an online Translator for this document. It could present the user with the document with all the text in editable boxes. Then anyone could log in, create a new language version, translate the contents of the text boxes and save it to the DB. After that, hit a button and the tool spits out a completed, correctly formatted HTML document for the language in question.

The advantages of this are many; one can save a partially completed language to the db and continue working on it later, or hand it over to a different translator. It might even be possible to link it into the google translation services, so that the initial output contains a suggestion for the entire page in the desired language. By adding some version and user control, it could become a one-stop work environment and library for everyone that is working on localisation.

EDIT: When i think about it, having this, it would be a small step to add all the text strings in Celestia, too...

Building something like that is not a small job, though, so don?t expect it right away...

- rthorvald

[BobHegwood]

You forgot to mention the Motherlode documentation page

Please note that the ML documentation page is obviously way out of date now. I'm sorry, but my health
and other circumstances have just not allowed me to update many of these.

That said, however, we would very much welcome ANY updated documentation. People here are far
better equipped to create these documents now anyway.

Christian has received a few comments concerning the FAQ from myself, and I am certain that he is doing a
great job here, so please continue. If anyone would care to upload revised documentation to the ML, I would
be more than happy to have it placed there.

Thanks, Brain-Dead

[ElChristou]

But confess, you used ElChristou readme for all the rest of text in that page. This one is from 2006 so, it will need a whole makeover.

If you read again my post you will see it's not *MY* readme, but the official readme, the HTML was done in 2006 but I put it up to date to match the actual official readme... (resulting in the exact content of svn...)

[Guckytos]

EDIT: You forgot to mention the Motherlode documentation page

No, i didn?t. I am NOT editing the texts at all, apart from a few logical necessities (like removing the reference to an external document that has become part of the actual text), everything is exactly as it is in my latest Celestia build. So anything missing must be supplied via an "official" manuscript.

It must be so since anything else would cause versioning problems between us; you or someone must be the "official custodian" of the content, and i will just take whatever is supplied and format it.

A note to Cham?s question on translations:
When i get some time i will look into the possibility of creating an online Translator for this document. It could present the user with the document with all the text in editable boxes. Then anyone could log in, create a new language version, translate the contents of the text boxes and save it to the DB. After that, hit a button and the tool spits out a completed, correctly formatted HTML document for the language in question.

The advantages of this are many; one can save a partially completed language to the db and continue working on it later, or hand it over to a different translator. It might even be possible to link it into the google translation services, so that the initial output contains a suggestion for the entire page in the desired language. By adding some version and user control, it could become a one-stop work environment and library for everyone that is working on localisation.

EDIT: When i think about it, having this, it would be a small step to add all the text strings in Celestia, too...

Building something like that is not a small job, though, so don?t expect it right away...

- rthorvald

BTW: Who IS responsible for putting "official" content into the svn, like translations and new documents like what we are just creating?

I am not sure, if it would be a good idea to start the work on an online translator now. Let's wait for the Qt Celestia with a unified UserInterface. Then the documentation could perhaps be really integrated into Celestia itself, in the form of some XML or gettext, which can than be easily translated.

We should know in what format the future help will be.

Please note that the ML documentation page is obviously way out of date now. I'm sorry, but my health
and other circumstances have just not allowed me to update many of these.
...
Christian has received a few comments concerning the FAQ from myself, and I am certain that he is doing a great job here, so please continue. If anyone would care to upload revised documentation to the ML, I would be more than happy to have it placed there.

Hey Bob, most of your comments have been taken into account already. I am just waiting for the comments of a certain other guy

You are doing a great job on the motherlode, and as big as it is, it is clear that you can't do everything at the same time. We are also there and the people that wrote the guides will eventually also write updates, perhaps, if you remind them kindly some time in the future.

Well, at the moment there aren't any big new features for STCs in the coming version, that I am aware of. (Apart from the "modify" command.) So, I think i won't update the guide this time.

Regards,

Guckytos.

[ElChristou]

...BTW: Who IS responsible for putting "official" content into the svn, like translations and new documents like what we are just creating?

The dev team.

[rthorvald]

I am not sure, if it would be a good idea to start the work on an online translator now. Let's wait for the Qt Celestia with a unified UserInterface. Then the documentation could perhaps be really integrated into Celestia itself, in the form of some XML or gettext, which can than be easily translated.

Well, there is some sense in that. Though the solution i suggest is practical, and can be run off shatters.net - a script that stores and retrieves all the text in the local mysql db and outputs a localized page on demand. You could output any format you desire, really - xml, too. It is just a matter of writing a fitting output template, once the system itself is up and running.

But let?s do this one step at a time, and complete this guide as it is now first. Let me know when you have something ready.

- rthorvald

[BobHegwood]

You are doing a great job on the motherlode, and as big as it is, it is clear that you can't do everything at the same time. We are also there and the people that wrote the guides will eventually also write updates, perhaps, if you remind them kindly some time in the future.

I thank you for the comments, my friend, but Ulrich (a.k.a. Adirondack) is the poor soul who has to do all of the
real work on the Motherlode. If anyone deserves thanks, please be aware that it is HE, and not me.

Be that as it may, however, we would BOTH welcome updates of any kind to the documentation.
Many thanks, Brain-Dead Bob