Fwd: Advice about where to start documenting API stuff

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Fwd: Advice about where to start documenting API stuff

Claire Wood
Hi

I wonder if I can ask some advice.  I'd like to have a go at
documenting the Calc/API stuff on the Documentation/Needwork Wiki page
if no-one else gets there before me and after I've done as much of the
Getting Started Wiki Guide as I can before I go away next week, but
not sure where to start to learn about the API's.  It's been a while
since I documented any programming so will probably need to learn from
scratch again.  Any tips on where I could start?

--
Best wishes

Claire Wood



--
Best wishes

Claire Wood

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Advice about where to start documenting API stuff

Clayton-24
On 02/14/10 20:46, Claire Wood wrote:
> Hi
>
> I wonder if I can ask some advice.  I'd like to have a go at
> documenting the Calc/API stuff on the Documentation/Needwork Wiki page
> if no-one else gets there before me and after I've done as much of the
> Getting Started Wiki Guide as I can before I go away next week, but
> not sure where to start to learn about the API's.  It's been a while
> since I documented any programming so will probably need to learn from
> scratch again.  Any tips on where I could start?

That's an ambitious project :-)

Basically the Calc section of the Wiki is written by developers (usually
non-native English speakers, which shows in the grammar etc.) for
developers.  The Doc Team hasn't touched that part of the Wiki.

If I was to work on it I'd probably take it in bits, starting with a
simple language cleanup, correcting the grammar and wording.  That will
give you a feel for what is involved in the API side of the docs, and it
will make what is documented there a lot more usable and readable.

 From there, I think the complexity rises quite a bit.  There is a
similar/parallel document called the Developer's Guide you can find
here:
http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide
with a chapter dedicated to Calc:
http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Spreadsheet_Documents

Working along-side the developers (you can find them lurking on the
[hidden email] mailing list) we could look at how the two
sections could be merged into one document (into the Spreadsheets
chapter in the Dev Guide).

C.
--
Clayton Cornell       [hidden email]
OpenOffice.org Documentation Project co-lead
Sun Microsystems, Hamburg, Germany

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Advice about where to start documenting API stuff

Claire Wood
Hi Clayton

I had a go at the API/Calc document on the Documentation/Needs Rework
part of the wiki whilst the Oooauthors site was down tonight.

See the following link:
http://wiki.services.openoffice.org/wiki/Calc/API/Programming

I corrected the grammar and some of the wording as you suggested but
as you can appreciate, as it has been some years since I documented
anything at API level, I may have used the wrong wording in some
places.  For example I have used the term "variable" which might not
make sense in the context that it has been used.

If someone can take a look at this page at some point and give me some
feedback, I'd be appreciative.

Kind regards

Claire

On 15 February 2010 02:21, ccornell - OpenOffice.org
<[hidden email]> wrote:

> On 02/14/10 20:46, Claire Wood wrote:
>>
>> Hi
>>
>> I wonder if I can ask some advice.  I'd like to have a go at
>> documenting the Calc/API stuff on the Documentation/Needwork Wiki page
>> if no-one else gets there before me and after I've done as much of the
>> Getting Started Wiki Guide as I can before I go away next week, but
>> not sure where to start to learn about the API's.  It's been a while
>> since I documented any programming so will probably need to learn from
>> scratch again.  Any tips on where I could start?
>
> That's an ambitious project :-)
>
> Basically the Calc section of the Wiki is written by developers (usually
> non-native English speakers, which shows in the grammar etc.) for
> developers.  The Doc Team hasn't touched that part of the Wiki.
>
> If I was to work on it I'd probably take it in bits, starting with a simple
> language cleanup, correcting the grammar and wording.  That will give you a
> feel for what is involved in the API side of the docs, and it will make what
> is documented there a lot more usable and readable.
>
> From there, I think the complexity rises quite a bit.  There is a
> similar/parallel document called the Developer's Guide you can find here:
> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide
> with a chapter dedicated to Calc:
> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Spreadsheet_Documents
>
> Working along-side the developers (you can find them lurking on the
> [hidden email] mailing list) we could look at how the two sections
> could be merged into one document (into the Spreadsheets chapter in the Dev
> Guide).
>
> C.
> --
> Clayton Cornell       [hidden email]
> OpenOffice.org Documentation Project co-lead
> Sun Microsystems, Hamburg, Germany
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>



--
Best wishes

Claire Wood

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Advice about where to start documenting API stuff

TJ Frazier
Hi, Claire,
What a marvelous job!

On 2/20/2010 18:29, Claire Wood wrote:

> Hi Clayton
>
> I had a go at the API/Calc document on the Documentation/Needs Rework
> part of the wiki whilst the Oooauthors site was down tonight.
>
> See the following link:
> http://wiki.services.openoffice.org/wiki/Calc/API/Programming
>
> I corrected the grammar and some of the wording as you suggested but
> as you can appreciate, as it has been some years since I documented
> anything at API level, I may have used the wrong wording in some
> places.  For example I have used the term "variable" which might not
> make sense in the context that it has been used.
>
> If someone can take a look at this page at some point and give me some
> feedback, I'd be appreciative.
>
> Kind regards
>
> Claire

I looked at all your changes. You've really cleared out the underbrush;
it's a big, big improvement.

To answer your specific question, "Object" and "Any" are /types/ so
"type" might be clearer than "variable".

The big problem I see with this humongous page is that it should be
broken into about five smaller ones, as a look at the TOC itself
suggests. Maybe Intro + link farm + "See also" as the opening page, plus
pages for "finding and inside a cell" (big page, here), "Cell Ranges",
DevGuide translation, "Listeners", and "Graphics". I am putting this out
for feedback; maybe somebody has objections, or a better idea.

Technical problem: I strongly suspect that those references to "SDK 1.1"
should read something like, "SDK 3.2" now. However, I am totally
unfamiliar with the Software Development Kit, as of yet.

Wiki tech: this page makes no use of the <tt>...</tt> feature, for
marking embedded words and phrases of code. (As a user, I find it very
helpful. It also eliminates some quotation marks.) Because the editor is
not equipped with the suitable button, I find it easier to copy the wiki
text to a Writer document, where I have written the proper macro to
handle the bracketing of a selected piece of text. I will do that, after
the "breakup" question is decided; no rush.

Again, thanks for the good work!
--
/tj/

T. J. Frazier
Melbourne, FL

(TJFrazier on OO.o)


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Advice about where to start documenting API stuff

Claire Wood
Hi All

First of all thank you for the feedback TJ.  I have updated variable to type.

With regard to the references to SDK versions, to save having to
update the documentation every time the development kit is updated,
would it not be better to have the reference as just "SDK", or are
different versions of  SDK running simultaneously?

Just thinking it might be a good idea because I once worked for a
telecoms software house that developed a development kit to go with
their software and they decided on a general reference to it to cut
down on the minor updates to the documentation.

Claire

On 20 February 2010 20:16, TJ Frazier <[hidden email]> wrote:

> Hi, Claire,
> What a marvelous job!
>
> On 2/20/2010 18:29, Claire Wood wrote:
>>
>> Hi Clayton
>>
>> I had a go at the API/Calc document on the Documentation/Needs Rework
>> part of the wiki whilst the Oooauthors site was down tonight.
>>
>> See the following link:
>> http://wiki.services.openoffice.org/wiki/Calc/API/Programming
>>
>> I corrected the grammar and some of the wording as you suggested but
>> as you can appreciate, as it has been some years since I documented
>> anything at API level, I may have used the wrong wording in some
>> places.  For example I have used the term "variable" which might not
>> make sense in the context that it has been used.
>>
>> If someone can take a look at this page at some point and give me some
>> feedback, I'd be appreciative.
>>
>> Kind regards
>>
>> Claire
>
> I looked at all your changes. You've really cleared out the underbrush; it's
> a big, big improvement.
>
> To answer your specific question, "Object" and "Any" are /types/ so "type"
> might be clearer than "variable".
>
> The big problem I see with this humongous page is that it should be broken
> into about five smaller ones, as a look at the TOC itself suggests. Maybe
> Intro + link farm + "See also" as the opening page, plus pages for "finding
> and inside a cell" (big page, here), "Cell Ranges", DevGuide translation,
> "Listeners", and "Graphics". I am putting this out for feedback; maybe
> somebody has objections, or a better idea.
>
> Technical problem: I strongly suspect that those references to "SDK 1.1"
> should read something like, "SDK 3.2" now. However, I am totally unfamiliar
> with the Software Development Kit, as of yet.
>
> Wiki tech: this page makes no use of the <tt>...</tt> feature, for marking
> embedded words and phrases of code. (As a user, I find it very helpful. It
> also eliminates some quotation marks.) Because the editor is not equipped
> with the suitable button, I find it easier to copy the wiki text to a Writer
> document, where I have written the proper macro to handle the bracketing of
> a selected piece of text. I will do that, after the "breakup" question is
> decided; no rush.
>
> Again, thanks for the good work!
> --
> /tj/
>
> T. J. Frazier
> Melbourne, FL
>
> (TJFrazier on OO.o)
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>



--
Best wishes

Claire Wood

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Advice about where to start documenting API stuff

Clayton-24
On 02/21/2010 01:06 PM, Claire Wood wrote:
> First of all thank you for the feedback TJ.  I have updated variable to type.

Hi Claire.

I have to agree with TJ :-) Your edits made that section a LOT more
readable.  Thank you!

The original authors (primarily developers) that section are not native
English speakers, so the grammar of their mother tongue tends to slip
into the words they write.... in much the same way I tend to use English
grammar when I write in Dutch (a second language I sort of know).


> With regard to the references to SDK versions, to save having to
> update the documentation every time the development kit is updated,
> would it not be better to have the reference as just "SDK", or are
> different versions of  SDK running simultaneously?

It is technically possible to use more than one SDK at a time (although
probably not that likely in practice).  With OOo, the SDK has changed
from one release to the next.  Documenting this is... a challenge.  Do
we document only the latest SDK? Or do we document all possible SDK
variations.. or do we document the latest method and add a Note with the
differences to past releases?  I'm not sure what the right answer is here.

In previous releases we had a much smaller number of differences... but
since the 3.x release of OOo, there is a rapidly growing number of
changes, and they are quite significant in some cases.

This is something we need to figure out... hopefully before 3.3 is
released :-) so any ideas you have are welcome!

C.
--
Clayton Cornell       [hidden email]
OpenOffice.org Documentation Project co-lead

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]