CiviCRM Community Forums (archive)

@lobo - I agree the book is nice, but having accurate documentation is even better, so I think we are doing the right thing by retiring the book. As Michael recently demonstrated with his training manual, a book actually can be printed from the wiki.

@jchester - I think you are right - debugging does not belong in the user/admin guide and you should take it out, reclaim that url, and move the stuff to the developer guide. You could link to it from the user/admin guide if that seems appropriate. I second Michael's point about curation. Be bold! Clean that stuff up! Rename the testing pages and anything else you see fit. I really like your proposal for the chapter structure.

Tim and I have been writing a lot of the Developer Reference pages, but some of those pages have stretched a bit past their scope and into the "guide" rather than "reference" territory. I think once we have a better structure in the wiki it will be easier to tease that stuff out.

Following on from some off-forum discussions I am posting my ideas for the structure of the document wiki.

I don't think it is a big change from what is already there, but perhaps I am suggesting a change in emphasis in some areas.

I have approached this from my perspective ie that of a fairly experienced user/administrator who has successfully modified system workflow messages and can see things that they would like to add but has no real coding experience. ie a non-techie who thinks fairly logically.

My idea is:

Overview – Aimed at someone like me but (parts of it) also of use to a techie meeting Civi for the first time (eg the codebase and also the preferred way to extend/alter it). It should let people know what options there are for extending/customising Civi and when each might be used, but not go into much detail.  I would say that everything that has a chapter in the Guide section should get a brief overview here.


Set-up – tells people what/how to set up what they need to be a (useful) civi developer.  The ‘useful’ part means contributing to the community, so this includes Civix so that they can package additions in extensions  and using git and github so that they can submit PRs rather than patches.

 

Guides -  Someone reading the overview should be able to think “Ah, what I want to do will probably work best by using A (and C)” then go to the correct page in the Guide for more details on and example of how to do things. It should refer to the current away things are done.


Reference – I would see this more as a place that developers go to when they know the process they should be using to do something but they are not sure of the exact hook they should be using or the  syntax etc   ( eg the hook reference).  I know that is not how it is at the moment for some sections but to quote from Coleman


 

Tim and I have been writing a lot of the Developer Reference pages, but some of those pages have stretched a bit past their scope and into the "guide" rather than "reference" territory. I think once we have a better structure in the wiki it will be easier to tease that stuff out.

Perhaps some things could be in both the guide and reference sections - in the guide with explanations and in the reference just as a list.

Legacy info needs to go somewhere (eg the legacy API stuff) .  It could fit into the Reference section or have it's own section.  If it contains the correct info then we could do away with previous versions of the developer wiki that makes using the site search to find current info somewhat tedious.


So, those are my ideas, but as I am not a developer I could easily be talking nonsense.  Comments and suggestions are obviously welcome.

Also, because I am not a developer I can't do much more than shuffle what is already there, so I would be asking for help from other people.


And finally, the book versus wiki question has been raised previously.  I would hope that the overview section from the wiki would also be able to stand more or less alone as an "Intro to Civi for developers" book with  directions to the wiki where appropriate.  Then the book should not need updating often and the wiki (which is easier to update) will contain the bulk of the info.

sorry - that sounded wrong. I'm looking forward to seeing you next month - is it still on :-)

@jchester this will probably become more clear as you work on it, but I'm wondering about how the structure can facilitate linking between guides and references. I think a lot of them will likely be in pairs. For example

Guide to Using Hooks <-> Hook Reference
Guide to Writing Javascript <-> Javascript Reference

While I do like the proposed structure that will place guides and references in separate sections, I think we need a convention of prominently linking between them. For example if every page in the wiki had a "See also" section at the top.