CiviCRM Community Forums (archive)

On http://wiki.civicrm.org/confluence/display/CRMDOC/Notes+for+New+Developers+and+Webmasters there is a link to the "civicrm architecture series" ( http://civicrm.org/architecture) but that page is not there.

The missing page along with references to ERD 2.0 and ERD 1.7 makes me wonder if the rest of the page is still relevant.

Can I assume that any page updated in the last 6 months will be mostly relevant?

(I have already nearly been caught out once with the developer book talking about svn rather than github.)

   

I think the most up-to-date stuff is http://wiki.civicrm.org/confluence/display/CRMDOC/Developer+Reference

We are thinking of getting rid of the developer book altogether. It gets out-of-date so fast, and it's hard to maintain documentation in more than one place.

Looking at the book and at the wiki it seems that the at the moment the book has more introduction/overview and the wiki has more examples/recipes.

As non-techie who dreams of dabbling around the edges of developing, the book was very useful in providing an explanation of coding concepts such as hooks.  I realise that info can be found on the internet, but it helped to have the basics in the one place.  If you decide to just have a wiki then can I suggest that some of the book chapters be transferred to the wiki.  I am happy to do/help with that.

Word of caution: use the unversioned space of the wiki (e.g. make sure version numbers are not in the url)
You should be at http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
not */CRMDOC43/*

Hi guys,

I am in the process of updating the developer guide (book). If we are removing it please let me know if I should continue with this exercise or if I am better of putting parts of the book on the wiki as jchester is suggesting. And I totally agree that the basic concepts would need to be explained on the wiki if we do remove the book.

Hey there,

I guess the key thing is making sure that all people who are working on developer documentation are talking to each other, and that we ensure that things are kept up to date.  Although we got some momentum behind the developer guide when it was initially published, apart from Erik's valiant efforts on API stuff a fair amount of the rest of it is getting out of date.  Since Tim and Coleman have been doing good work on the wiki, it feels like we have got two separate places where developer documentation is happening and that is unecessary duplication of effort and it is probably time to consolidate.

To my mind, two key 'minus points' about developer documentation at the moment are lack of curation and the weird/bad versioning. I think we can solve both

Re: curation, although we are good at adding new content to the wiki, we aren't as good at consolidating it - we hope that bit will happen magically, but it doesn't and it gets messy - it's a bit like if you were to go to Wikipedia and find 6 different articles on London.  I think that curation is a bit of extra effort, but it is necessary to keep the wiki in good order.  I think the problem here is that we don't have any wikipedians like wikipedia, who feel like they know the documentation enough to make the call on when a page should be deleted / merged.  People come in and make edits, but don't feel like they have the authority to refactor other people's work. I think that is slowly changing and we should encourage it more. One thing we could do to improve that would be to ensure that there is a developer documentaion team who can do this / help out with this.  It feels like Erik, Joanne, Tim and Coleman would be good people for this team.  Are all you guys on http://lists.civicrm.org/lists/info/civicrm-docs ?

If we set up some guidelines along the lines of

* all documentation people should be on docs mailing list http://lists.civicrm.org/lists/info/civicrm-docs - it is very low volume (unfortunately )
* if you think that a refactoring could be controversial or you are unsure about whether to do it, discuss on docs@lists.civicrm.org.

Re: versioning the wiki, it seems to have introduced many more problems than it has solved, i.e. we are helping the minority who are developing on older versions at the expense of the majority who are developing on newer versions.

What needs to be versioned in the wiki? It seems like the version that a hook, api, or other technique was first available is important (fyi http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_xmlMenu has no version info but http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_emailProcessor does).  Installation instructions are specific to a version.  Potentially we can solve that by having a page for installation instructions for each version.

What else would we be loosing if we got rid of versions?

1.  A conflict - from an unexpected source. 

There is a page called Debugging in the User and admin wiki http://wiki.civicrm.org/confluence/display/CRMDOC/Debugging

That meant I had to rename the debugging section from the developer book as debugging for developers http://wiki.civicrm.org/confluence/display/CRMDOC/Debugging+for+developers .

I have no problem with the rename, but am very doubtful about having a debugging page in the user and admin wiki.  I would have thought that almost by definition a User and Admin guide would deal only with things relevant to a production site which debugging isn't.


2.  A rewrite required?

With the switch to git and git hub it seems to a me that attaching a (diff file) patch has been replaced by submitting a pull request.  This would mean that much of http://book.civicrm.org/developer/current/introduction/fixing-bugs/ needs updating.

I am happy to have a go at it (based on my vast experience of PRs ), but before I do so, is a PR the only way to supply bug fixes now or can people still attach patches to issues?

3.  The chapter on testing in the book and the  unit testing page in the wiki need to be reconciled.

To me it seems that the wiki page unit test  http://wiki.civicrm.org/confluence/display/CRMDOC/Unit+Tests/ should be renamed testing as it covers both unit tests and web tests.   However there is also a non-document wiki page called testing  http://wiki.civicrm.org/confluence/display/CRM/Testing  - will that be too confusing? 

Also, it seems to me that at least some of the document wiki links are for developers who work closely with the core team rather than your 'everyday' developer.  ( Eg "Results of test case you are assigned to" on http://wiki.civicrm.org/confluence/display/CRMDOC/Testing  and all of http://wiki.civicrm.org/confluence/display/CRM/Introduction+to+working+on+test+coverage)

What sort of testing is expected from an 'everyday' developer?  I think this section is beyond the limits of what I can usefully do without some very clear guidelines.