On 03.02.2006 10:14, Tahir Javed wrote: > IMHO, we should have two seperate levels of documentation, or in other > words, a "User Manual" and a "Developer Manual".
What is a "user" here? What is a "developer"?
Crystal Space is an SDK, so the users of this SDK are developers again,
but then there are also the developers that develop CS itself. To avoid
confusion, perhaps clarify what you mean.
Also note that the manual has recently been restructured, starting with
introductory sections ("Introduction", "Installing", "Running"), and
then different sections focused on developer users ("Using CS"), artist
users ("Working with Engine Content") and information relevant for CS
contributors. So perhaps the manual isn't that far away from your
proposed "split".
> In line with that, the download page at main CS website should clearly have
> two seperate areas, one that says "If You are New..." or something like that
> and the other clearly says "For Experienced C/C++ developers"...
"New" to what? A first-time visitor is certainly to new to CS itself.
Also, C++ experience is somewhat of a requirement to use CS. I'm not
sure whether distinguishing between "experienced" and other C++
developers is a good idea. If you don't know the SDK you don't know it,
no matter the amount of C++ you coded; introduction into the SDK is
needed in either case - I don't think we should or can provide any
introductions to C++ itself.
> To summarize, there is no point to confuse a novice with having to choose
> from multiple options to achieve the same result (to use CS or CEL, to
> create world with XML world files or Blender or 3dsMAX, to create Terrain
> with Terragen, Blender or the native terrain generator, to use VC++ 6 or 7
> or 8 or CygWin etc. Etc.) This feels like a maze and one cant find a simple
> straight path to follow.
Giving a "straight path" can also backfire: the developer who wants to
build a game for OS/X and cross-compile for Win32, whose artists use
3dsmax, may think turn away, thinking that the presented options are the
only ones.
We should make recommendations for tools which we think are preferable
due ease-of-use and/or support (e.g. Blender), but at the same time, we
should point out that other options are available.
-f.r.
signature.asc
Description: OpenPGP digital signature
