PING: Clayton Cornell - Re: [documentation-dev] Fwd: Advice about where to start documenting API stuff

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

PING: Clayton Cornell - Re: [documentation-dev] Fwd: Advice about where to start documenting API stuff

Claire Wood
Clayton

I did the grammar check on the Calc/API page on the Wiki and had some
feedback from TJ.  I read the spreadsheet link you sent me below and I
must admit it's totally over my head at this point, as I've only been
with the project since 29 January.  I'd need some guidance as to what
sections should go together and how to go about merging the two
documents because I don't want to lose the accuracy because otherwise
I think developers would get a tad upset with me (lol).  I am keen
though to help clean up any areas that need it as I need the
experience.

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide


http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Spreadsheet_Documents

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: PING: Clayton Cornell - Re: [documentation-dev] Fwd: Advice about where to start documenting API stuff

Clayton-24
On 02/21/2010 09:26 PM, Claire Wood wrote:

> Clayton
>
> I did the grammar check on the Calc/API page on the Wiki and had some
> feedback from TJ.  I read the spreadsheet link you sent me below and I
> must admit it's totally over my head at this point, as I've only been
> with the project since 29 January.  I'd need some guidance as to what
> sections should go together and how to go about merging the two
> documents because I don't want to lose the accuracy because otherwise
> I think developers would get a tad upset with me (lol).  I am keen
> though to help clean up any areas that need it as I need the
> experience.
>
> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide
>
>
> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Spreadsheet_Documents

I'm not 100% sure how to go about merging the sections either.  What we
can do is ask one of the developer leads (Jeurgen) and see what he
thinks - he will probably be the best judge whether it's possible or
practical to merge the sections, and may have some advice as well.

Even if it ends up not being practical to merge the info, the work you
did on cleaning up the Calc pages is great!

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

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

Reply | Threaded
Open this post in threaded view
|

Re: PING: Clayton Cornell - Re: [documentation-dev] Fwd: Advice about where to start documenting API stuff

Juergen Schmidt-3
On 2/22/10 8:46 AM, Clayton wrote:

> On 02/21/2010 09:26 PM, Claire Wood wrote:
>> Clayton
>>
>> I did the grammar check on the Calc/API page on the Wiki and had some
>> feedback from TJ.  I read the spreadsheet link you sent me below and I
>> must admit it's totally over my head at this point, as I've only been
>> with the project since 29 January.  I'd need some guidance as to what
>> sections should go together and how to go about merging the two
>> documents because I don't want to lose the accuracy because otherwise
>> I think developers would get a tad upset with me (lol).  I am keen
>> though to help clean up any areas that need it as I need the
>> experience.
>>
>> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide
>>
>>
>> http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Spreadsheet_Documents
>
> I'm not 100% sure how to go about merging the sections either.  What we
> can do is ask one of the developer leads (Jeurgen) and see what he
> thinks - he will probably be the best judge whether it's possible or
> practical to merge the sections, and may have some advice as well.
>
> Even if it ends up not being practical to merge the info, the work you
> did on cleaning up the Calc pages is great!

Let me explain the main idea and initial structure of the DevGuide in
relation to other useful wiki pages/guides.

The main idea was to create a reference documentation for developers,
authors with technical background and experienced users. The Devguide as
basis for additional developer documentation like the Basic Guide or the
C++ section in the wiki where the page you have referenced belongs to.

The DevGuide is structured or should be structured to explain basic UNO
knowledge as well as more detailed core knowledge of our component
model. This base UNO stuff covers language specific sections for C++,
Basic etc. But the main part of the DevGuide explains API concepts and
general APIs split into different chapters. Ideally all the concepts are
explained in detail and are linked to an example (part of the SDK). We
agreed initially to focus on only one language (Java) for the examples
to make it easy to follow.

I think it make sense to focus on one example language and reference to
additional guides/books where other languages are covered mainly. The
API concepts are always the same and can be adapted hopefully easy. But
it makes of course sense to have these other guides like the Basic guide
to focus on completely different user groups and explain the API usage
in a slightly different way and more appropriate for these user groups.

The C++ section in the wiki is a very good reference and collection of
useful pages for C++ developers. Maybe we can use this stuff and can
create a even better structured C++ Developers guide. Such a guide would
be a perfect reference for developers who want to dive a little deeper
into our huge C++ code base.

Juergen








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