Author Topic: Documentation and book (Read 20143 times)

e_mason · August 15, 2011, 07:46:39 am

Rescheduling IRC chat for 16:00 PDT today... which should mean 23:00 UTC (?). Hopefully Erich,Eileen, and other late sleepers in the lower 48 and night owls in Europe can make it

bpmccain · August 16, 2011, 08:16:29 am

I'd love to get involved and I'd definitely fit into that 'Beginner' category. A task list of stuff I could start with as I ease my into this would be fantastic.

I've got a feeling I'm going to be using CiviCRM for the considerable future, and I'd like to get to know it really well.

+1 for that idea!

Erich Schulz · August 17, 2011, 07:42:13 pm

i'm going to try to keep contribute where I can, but don't think I'll get much of a chance to engage on IRC - the chunks of time I get on this stuff tend to arise too randomly for that between family, volli committments (which is where civi sits for me) and "day job" stuff

Eileen · August 18, 2011, 12:41:44 pm

Mason, what time zone are you in? Maybe when the sprint is on might be a time to tee something up - there will be lots of documentation talk going on! Although I think the focus is updating the Floss manual

Donald Lobo · August 18, 2011, 01:21:08 pm

I'd really like to see us putting some time and effort into: "Making it easier for the newbie to contribute to CiviCRM" and figure out what we can do. maybe mason / eileen, me (and anyone else interested) can chat today/tomorow?

lobo

bpmccain · August 18, 2011, 01:40:32 pm

What time? I'd like to be part of conversation.

Donald Lobo · August 18, 2011, 02:09:09 pm

how about 7:00 am pacific time tomorrow morning

thanx

lobo

bpmccain · August 18, 2011, 03:14:35 pm

I'll aim to be there

Erich Schulz · August 19, 2011, 10:03:52 am

lobo i'll try to document my thoughts -sorry the irc just doens't work for me as i get interrupted too often when i'm tinkering

i really think the primary issue is documentation

if the floss manual could take comments - like php or mysql man pages that would be a huge leap forward
- > then the wiki could be shut down (with code contributors encouraged into github), the doc sprints could then trawl the contributed comments

then encourage doc contribs as explained by eileen, (btw also where are the phpdocs generated?) then encourage noobs to help document the api (in its broadest sense)

sorry Xavier, but I really think the v3 api is overemphasised as sql is a far more accessable technology (powerful, concise, no programming required, verry very very well known and easier to learn than programming) - i think using both sql and the api will make civicrm more 'open' in a variety of ways - again not to dis the v3 api but its only one piece! (imho)

what i want for chistmas is for some noobs to interview the core team and document the non-entity (ie non-v3) api and the few mysql gotchas in the db

just my thoughts, hope that helps

e

xavier · August 21, 2011, 01:59:34 am

Hi,

Friends don't let friends close to the sql. Too powerful, civi isn't 3NF enough and mysql isn't sql enough.

SQL is fine, but too close to the metal for a casual hacker to do something in civi. Schema change between versions, sometimes in subtle and hard to see the impact ways.

In one year or two, when some of your queries don't work because the schema has changed, or even worse, when it changed and the queries still run but corrupt the data is hidden an vicious ways, that will explode at your next upgrade, or when you are using a non common function, we'll re-discuss it.

If you know your foreign keys, are the king of on delete cascade, is prepared to dig into the "non sql" parts of kind of weird foreign keys (eg civicrm_table) used here, feel brave enough to face the sql relationships between activities and contacts and you're prepared to updated your knowledge about the schema, you will benefit from sql and it will be faster than the api.

It would be great if you could document the schema better indeed.

If you want to quick hack in a safer way that will be more future proof, use the api. This being said, it's open source, and it's your data. By no mean am I going to use force to stop you sqling your way in the guts of civi

X+

fen · September 23, 2011, 07:42:11 am

I've been head down and completely missed this:

Quote from: Eileen on August 13, 2011, 12:53:28 pm

And, on the basis that any API behaviour that isn't tested should be treated as a random co-incidence not a feature, and under no circumstances documented or relied on in production code I also added a test.

Re:

Wow - thanks, Eileen! Sheer wizardry...

Eileen · October 12, 2011, 03:06:49 pm

Hi

Quite some time ago we followed this conversation through with a discussion on IRC & the feedback at the time was that the preferred option was to improve

http://api.civicrm.org/v3/

So that it both included the examples and the information about the API generated by the code (this is the same information accessed through the API explorer). I personally like this option because it encourages people to bond a bit more closely with the code & to improve the in-code comments.

I would note that Xavier has also improved the in-install view onto the information provided by getfields.

So, both the static documentation & the in-install documentation are generated by the same code functions - meaning the way to improve them is to improve both.

We have some progress on the phpdoc now = the activity_create function is now calling getfields to generate the documentation. There are still some things that aren't quite right - per the first ticket.

The second ticket covers the mechanism for flagging fields as 'required' or adding fields to getfields.

http://issues.civicrm.org/jira/browse/CRM-8898
http://issues.civicrm.org/jira/browse/CRM-9019

Are the people who were interested in helping still interested?

The Next Wave · March 30, 2013, 06:05:46 pm

So as a relative newbie- who has been playing with CiviCRM for at least 4 years- and also with SugarCRM, vTigerCRM and who knows what else-
I agree with a comment 2 pages back- having the Wiki and the FOSS Manual is not helpful.
I've been trying to solve problems- I find a lot of the information in both- either on a google search- or via links from the forums- and or, just looking things up.
When you change menu items in the core- like the Administer>Customize Data and Screens
now it's wrong in two places.
Meaning- nice newbie who is willing to help- has to think- "what are these fools doing" making it doubly hard for me to update the documentation? And- now, it's doubly hard for someone to make sure I didn't screw it up.
You have limited numbers of participants willing to work on this- don't make a system that takes double the time to do minor repairs- think about major ones?
With every new commit you make to the code- these can be referenced a lot of times- how am I supposed to fix them all.
My suggestion- ditch one or the other.
My other suggestion is going to get booed- but, Wordpress is now powering something like 1/5th of the sites on the web. Drupal can't come close. It's time to really try to put efforts into core functionality across all platforms-
and also to figure out how to do a wordpress plugin style updating system. The sooner you gain users in the much bigger sandbox- the quicker things start to get funded- fixed and working.

Erich Schulz · March 30, 2013, 08:43:16 pm

Quote from: The Next Wave on March 30, 2013, 06:05:46 pm

I agree with a comment 2 pages back- having the Wiki and the FOSS Manual is not helpful.
...
My suggestion- ditch one or the other.

uh-huh

if you keep the wiki I also think the habit of making a new version with each release is also unhelpful:

* trashes the history
* breaks all the links

better to just put up with some sections identified as (version 3.4-4.1:) etc

sorry that - yet again, still, am not able to commit to bitter contribution to civi beyond unsolicited advice :-) but deep respect to all the core team

Donald Lobo · March 30, 2013, 09:47:48 pm

we do hope that at some point the unsolicited advice is converted into some real patches and improvements to the system. While we do love and listen to advice / requests / suggestions, ultimately it is patches and improvements to the book / wiki that have a larger and more significant impact on the project

The doc team has spent a fair bit of time on wiki vs book and has come up with this page:

http://wiki.civicrm.org/confluence/display/CRM/Documentation

Bottom line: Writing, Maintaing and updating the book (or the wiki) is a LOT of work and we need more hands. If you can update one thing, update the book

we need folks to participate in book sprints and help review and improve current stuff, adding new stuff and migrate stuff from the wiki to the book.

lobo

CiviCRM Community Forums (archive)

News:

Author Topic: Documentation and book (Read 20143 times)

e_mason

Re: Documentation and book

bpmccain

Re: Documentation and book

Erich Schulz

Re: Documentation and book

Eileen

Re: Documentation and book

Donald Lobo

Re: Documentation and book

bpmccain

Re: Documentation and book

Donald Lobo

Re: Documentation and book

bpmccain

Re: Documentation and book

Erich Schulz

Re: Documentation and book

xavier

Re: Documentation and book

fen

Re: Documentation and book

Eileen

Re: Documentation and book

The Next Wave

Re: Documentation and book

Erich Schulz

Re: Documentation and book

Donald Lobo

Re: Documentation and book