Karl Weber wrote:
Hi Juergen,
first of all, thanks for your long answer. Please find my reply below.
Am Montag, 16. Februar 2009 22:25 schrieb Juergen Schmidt:
Hi Karl,
let me describe what i have in mind ...
First of all i would like to reduce the size of the SDK and i would like
to remove most of the examples. In case of the Java examples it
definitely makes sense to provide NetBeans or Eclipse projects because
it simplifies the whole stuff a lot (easy building and debugging through
the code).
So the idea is to provide in a first step NB projects for the Java
examples of SDK (more or less done by Ariel -> many thanks again,
http://wiki.services.openoffice.org/wiki/API/Samples/Java) and document
them in the wiki. Well the wiki should explain the examples in general
and on potential subpages the specific details for NB or Eclipse
projects are explained. Ideally we will have the examples available not
only in Java but alos in C++ and Python. That means MS Visual Studio
projects, maybe XCode projects, etc.
The DevGuide will still present related code snippets and of course
should provide links to the main example wiki page. Java as the
preferred example language should remain in the DevGuide. But as
mentioned before we would ideally have the examples in different
languages available.
Users can easy checkout the example sources from the code repository and
can use them in there preferred IDE. Currently they can be easy
downloaded as zips.
The advantage of this approach is that we can reach more potential
users. And of course advanced users can easier help to improve the
examples, fix problems etc.
It's still a lot of work to provide good example that are well
documented ...
Often the developers don't focus on developer documentation and
examples. But we need it and it is a good opportunity for new developers
to get started. Working on examples, understanding the concepts and help
others to understand what they have learned etc.
Later on the next step to work on or with the real office code should
become easier...
Juergen
Hmm, may be it is too late already, but I do not quite understand your idea.
So let me try to express it in my words:
(1) The DevGuide, in particular with respect to presenting only code snippets
in Java, should remain as it is.
(2) Boxes with code snippets in the DevGuide should have a link to the one(!)
main examples page. So, starting from a code snippet in the DevGuide I click
one link to get to the main examples page.
no, not a main example page of all examples. A main page for the
specific example where the snippet is from. In the old DevGuide we had
the links to the Java files in the SDK because the DevGuide came with
the SDK.
(3) The main examples page contains a list of all examples available. On this
page I can click on another link to get to another page that discusses the
particular example in Java (or any other language) which contains the code
snippet from (1), where I started. (One page for every example or even one
page for every example _and_ every language?) From this page, I can again
navigate to other pages, giving me particulars about the project files for NB
or Eclipse or, ... On these pages I might also find links to download the
project files for the particular example for the respective IDE.
no, the example page should explain the example in more detail and you
will find links to NB or Eclipse or whatever IDE projects to simply the
usage if you want.
We can also add links to the plain source files, either on this example
page or in DevGuide directly.
Juergen
PS: i agree to Ariel that we should move further discussion to d...@api
If this is what you mean, where do I find the code? My idea was to start from
(1) and find a link to a page where I can read the code on-line. A very good
example about what I have in mind is [1].
When I learn something like UNO I don't have to build and run every example.
Very often it is enough to just read the code. So it would be great if I
could read it by just clicking some links -- refer to [1] again.
It would be cumbersome, if I had to download the example and install the
project in an IDE in order to just read the code. Even worse, what if I don't
use NB, and don't want to use it? If the examples are available only as NB
projects, chances are high, that I will not only get frustrated, but that I
will loose interest.
O.K., my idea will not work for BASIC examples with dialogs. These examples I
will have to download and open with OOo.
To summarise:
(a) It is not clear to me, whether your idea will incorporate the possibility
to read code on-line or not.
(b) How many pages should there be for every example (see question above)?
-Karl
[1]
https://developer.mozilla.org/en/Viewing_and_searching_Mozilla_source_code_online
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
