ANDREA wrote:chris wrote:Andrea, I would appreciate some suggestions on how to improve the documentation. Vincent, Selden, myself, and others have been contributing to the Celestia WikiBook, which has a lot of information on creating SSC files:
http://en.wikibooks.org/wiki/Celestia/SSC_File. How could it be better organized? Would more tutorials be useful? More examples?--Chris
Chris, sorry if my post appeared as criticism to you and the other developers, this was not my intention.
In my opinion the problem (or MY problem, may be I'm the only one having it) is that, while I was used to and appreciated a lot e.g. Don Goyette's cel scripting guide, clearly written and filled with many examples, the other stuff made up to now is resulting, at least for me, in a plethora of information spread in a lot of posts, without any "compendium" of similar shape.
Yes, I know we have the Wiki ssc instructions page, and many more (Trajectories-Rotation Models-Using JPL Ephemerides with Celestia-Reference Frames), but it's missing a lot of examples, perhaps most of them, and this makes difficult and hard to understand a matter that, believe me, is not so well known by many Celestians, even if probably most of them will never admit it.
Well, I do take this as criticism, but it is
useful criticism. I will try to supplement the Wiki pages with more examples, though it will take time.
As you say, the Wiki pages on ssc (as all Wiki pages), are a collaborative gathering of information written and thought by different people, with different experience, feeling and behaviour with the subject.
For this reason I’m dreaming of a one-man instruction file, containing a lot of practical examples, that as you know are the best way to understand the matter in a shorter time.
I agree that it would be great to have such a guide. The documentation on the Wiki is rather technical, and I make no apologies for that: such documentation needs to exist. But, it could be better organized and illustrated with more examples and diagrams. It still would not take the place of a friendlier guide to Celestia add-on creation. There are two classic books documenting OpenGL: one is the Reference Manual, the other the Programming Guide. The Reference Manual is comprehensive, with pages organized alphabetically by function name. The Programming Guide is organized by topic, starting from basic 3D concepts and building to more advanced ideas. Celestia needs a Programming Guide.
BTW, just an example on Wiki problems:
Beginning f or "AAAA MM DD HH:MM:SS"Specifies a time before which the object doesn't exist.
The Beginning time may be provided as a
floating point number, in which case it is interpreted an
astronomical Julian date, or it may be provided as a quoted string, in which case it is interpreted as a Gregorian date.
If it is a quoted Gregorian date, AAAA MM DD = year, month, day (integers); HH:MM:SS = hour, minute, second (integers). Since version 1.3.1, Celestia converts these time-stamps into Julian Dates internally. A date to Julian Date and back converter can be found at the U.S. Naval Observatory
http://aa.usno.navy.mil/data/docs/JulianDate.htmlSincerely, do you think that all Celestians know what “
floating point number” is meaning?
Or what's the
Astronomical Julian Date?
Wasn’t perhaps needed to explain that the JD is written this way: 2443711.139953?
More: why the beginning date is given as “
AAAA MM DD” and no more as YYYY MM DD” as previously?
More: in the previous ssc definitions, written by Ulrich and Bob, it was given that "beginning" and "ending" could be written without the seconds, or with the AAAA MM DD only, so that it was possible to write as follows:
Beginning "1989 10 19 92:47:25" or
Beginning "1989 10 19 92:47" or
Beginning "1989 10 19"
Is this still OK?
If yes, it's missing in the wiki.
More. The web link to the U.S. Naval Observatory is OFF from many months, but this is the new one
http://www.aavso.org/observing/aids/jdcalendar.shtml
Yes, there are inadequacies in the documentation. Some more examples would help a lot, the AAAA instead of YYYY (presumably A = annum) was a poor choice, and there needs to be clarification about what date formats are allowed. I do think that terms like floating point number and Julian Date are appropriate as well--they have precise means that are widely understood by a certain audience. Without them, the concepts can remain fuzzy.
Please don't say me "why don’t you make it?", I would be very happy to be able to give my help on this, I always try to give my help with the little things I'm able to do, but I'm missing at least two most important characteristics, both highly needed for this task:
English is not my mother tongue (so I need a lot of time to understand what I read, and even more to try to write something intelligible),
and, most important,
I have not the culture needed to be able to modify the wiki ssc, sorry.
I won't ask you to make it, but I will ask you to help out.
The whole point of making the documentation available as a Wiki is to get more people to contribute to it. You don't have to write new documentation--simply fixing the broken links to the Julian Date calculator is a useful contribution. Just click
edit on the page and make the change.
Given I’m trying to give suggestions, I see that in the last months there have been a lot of patches, SVN, beta releases and so on, chasing each other at very short intervals, and this produces a lot of confusion in many people, I think.
It looks like, instead of officialising the already established new stuff, you and the other developers are going on and on searching for new improvements.
I beg your pardon Chris, I'm and old man, so be patient with me, please, but I feel that following all Celestia partial and beta improvements is becoming harder and harder as time goes by, given the missing of clear and SIMPLE explanations on how to apply them.
We have no more the time we had previously, between one release and the other, that allowed most of us to digest innovations, and to learn to use and appreciate them.
I'm sure that most of the new stuff is not used by most of people, due to the increasing difficulties to learn to use it.
Have you got seen how many people are still using older releases?
Allow me to remember what a high school professor told me many many years ago:
“...the best project, if poorly documented, will always be overtaken by another that, even if of lower quality, is very well documented”.
As I told, this is my feeling, but I would like that at lest once the silent people, i.e. the thousands of Celestians that never or very rarely write in the forum, would change their way of life, and may tell us if I’m wrong or right.
Bye and, as always, a lot of appreciation for all what you and all the other developers are doing to make Celestia better and better.
Friendly
Your suggestions are certainly appreciated.
The SVN versions and patches are a good thing; they are intended to allow people to experiment with new features and give feedback before the official release. I expect that most people are content to wait for an official release, which is just fine. That's how I am with most of the software that I'm interested in.
While 1.6.0 is under development, it would be useful to have some good overviews of the new features. For that purpose, I've created this new page on the WikiBook:
http://en.wikibooks.org/wiki/Celestia/160FilesHopefully, the feature descriptions are good enough to be reused in some more official documentation. I will continue to add to the page and add more details.
--Chris