Documentation and book

[xavier]

Hi,

A whole new section in the book has been written about extending and developing with civicrm:
http://en.flossmanuals.net/CiviCRM/DevelopIntro

API
The api chapter (from php, ajax, REST interface and the template):

http://en.flossmanuals.net/CiviCRM/DevelopAPI
the wiki describing each of the available api
http://wiki.civicrm.org/confluence/display/CRMDOC/Using+the+API
and an automatically generated documentation:
http://api.civicrm.org

HOOKS
The hook chapter
http://en.flossmanuals.net/CiviCRM/DevelopHooks

and the wiki
http://wiki.civicrm.org/confluence/display/CRMDOC32/CiviCRM+hook+specification

If we point you to this page as an answer to one of your questions, we are not RTFMing you, but it looks like you are blocked on a specific detail because you haven't yet the bigger picture clear in your head.

I'd recommend you to read the chapter(s), developing for Civi will be a much less frustrating experience. Personal anecdote: I even almost find it enjoyable .

If you find the wiki unclear or missing an explanation, please amend it. If you write something that might be useful to others, please share.

If you are not sure about how to do it, you might want to ask in the forum before starting to code, one of us might think about a faster way to get you where you want, or we might suggest a simple amendment that might benefit make your solution much more generic and so others can benefit from it.

X+

[ken]

Xavier,

I found that chapter the other day, following a link from a post, and I agree it's a useful and illuminating read. <applause/>
Thanks for your hard work!

Ken

[Erik Hommel]

All,
the book has helped me a lot in my first major development project, and I would recommend it to everyone!
Erik

[Erich Schulz]

A whole new section in the book has been written about extending and developing with civicrm:
http://en.flossmanuals.net/CiviCRM/DevelopIntro

oh just found this post... and followed the link with glee... but it's dead :-(

[Erik Hommel]

Eric,
the link is now http://en.flossmanuals.net/civicrm/ch062_introduction/
Erik

[Erich Schulz]

ok dumb question - what is the difference between wiki and book? and um, er, why is the authoring effort being splintered?

[Erik Hommel]

The book as in the floss manual is a more structured approach to create a guide on CiviCRM. On top of that there is the Packt-book which is a commercial initiative. The wiki is a more dynamic collection of interesting, not-so-interesting, useful and less usefull documentation.
The authoring is splintered because most of it is done as community work and we also have jobs that require some attention 
Erik

[xavier]

Hi,

The aim of that post was to provide a quick intro and pointers to various documents. I will update the urls and add the wiki and other newer resources. I will also take the liberty to delete your posts once done and put it read only/no comment (assuming I can find how to do that) to get back to a quick intro form and not long discussion;). Shout if you object and I will do that in a new thread instead.

[Erich Schulz]

cool - I was just wondering if the floss book really adds anything other than further splintering the documentation effort (i'm thinking here about technical documentation more than user)

currently there is:

- floss manual
- this forum
- code generated comments at http://api.civicrm.org/v3/
- the wiki

I can see a clear rationale for the last three - but the floss manual? I'd have thought the best strategy is two push everything into the last two... ideally most forum questions would link to the back to the wiki

ie some posts a really good question that deserves a answer, and the person that knows posts a link back to the wiki page they just edited

just a suggestion of course! i remain grateful for any assistance I receive in any place!!

those pesky day jobs are a real nuisance!

;-)

[e_mason]

I'd like to help with documentation of the APIs (primarily adding input array definitions, return array examples).

How can I do this?

[Eileen]

Did I hear someone say they would like to help!

there are currently 3 types of code generated documentation - the phpdoc - I need to find out why that doesn't seem to be updated, the examples in the api folder on your install and the api explorer are you referring to one of these?

[xavier]

Hi,

Not sure if it's because there isn't enough documentation or because it's hard to find (isn't necessary exclusive).

Thanks very much for your help offer, can we start by using your still fresh point of view to see how someone that isn't too involved in the api see the doc?

http://wiki.civicrm.org/confluence/display/CRMDOC40/CiviCRM+Public+APIs
Are the various documentations options clear and useful?

I personally do use the explorer as documentation, both to check what parameters are returned, and to use the getfields action to list the fields (that are the parameters you can use for input/output params). Not sure if this is the easiest strategy, nor if it's known.

X+

[e_mason]

Fresh is right!  I had blown right past the API explorer.

Here's what I find:
The current wiki docs aren't useful for starting out.  After further digging, I understand an entity!
Per my other post/problem the bindings for Drupal aren't clear.  Once I figure this out, I'll add a page there!
and the in-API documentation (used by Explorer and the api dot civicrm dot org page (stupid newbie status...)) are lacking things like full specification of input parameters.

For instance, on the api civicrm org page , the docs for activity_create function provides most (but not sure about all...) the input parameters, but the returned array isn't given.  For activity_get the parameters aren't specified at all.  But if I go to the API explorer I have NO information about the input parameters even for activity_create.

Yes these can be figured out, but it would be nice to have them available.  Since I'm slowly building up my own library of input parameters I though it would be great to add them into the API code itself.

[Eileen]

Mason - the other place is the examples - eg.

http://svn.civicrm.org/civicrm/branches/v3.4/api/v3/examples/ActivityCreate.php

The examples are generated out of the test suite which makes them a bit more guaranteed.

[xavier]

Re: list of params. I'm not sure we can maintain manually a list, and would much prefer having it automatically generated.

using the action getFields on any entity will help you getting it. Granted, the presentation is not super sexy. Would a button "display list of params" be useful on the api explorer or somewhere else?

X+