[Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?

[Derek Hohls]

David

You wrote "(You) just absolutely have to make user-friendly documentation about your product, especially the api you keep talking about."

I have been on the mailing lists of numerous open source projects over the years, and someone always raises this.  Why?  Well, its true.  However, asking and getting are two different things.  A commercial company will just hire someone and pay them.  A big company (E$RI) will hire someone really good and pay them accordingly. An open source project cannot do so.  It only happens if there is someone (or ones) who is  (a)  passionate about documentation, (b) knows the system very well and (c) has the spare time to write (and writing is very time consuming).  Sadly, this does not always happen.  In an open source project the primary goal is to solve Real Problems with Real Code; and that goal attracts programmers - who care about good code and not "user-friendly documentation" - and not so much documenters.  

Not wanting to be negative - just hoping to guide your expectations!

Derek

PS If you have the time, there is an interesting article on the differences between Linux and Windows (http://linux.oneandoneis2.org/LNW.htm); section "Subproblem #3a: There is a culture" is of relevance here, as is "Problem #5: The myth of user-friendly".  My favourite quote from that article is "Linux is not interested in market share. Linux does not have
customers. Linux does not have shareholders, or a responsibility to the
bottom line. Linux was not created to make money. Linux does not have
the goal of being the most popular and widespread OS on the planet."  My personal view is that QGIS is in a very similar position...


>>> "Chrest, David"  10/12/13 4:19 AM >>>
Thanks so much for the info Richard.
Gary's PyQGIS Programmers Guide looks like just what I was talking
about. Glad to see this book will soon (hopefully) come out. Should be a
great and fill a much needed void.

No, not being paid by ESRI :-)  I just know that the first thing people
look for is god documentation about software. That alone can be the
deciding factor before somebody looses interest or finds it too
troublesome to work with. Make things so much easier to figure than
going on a hunt every time you want to do something. Plenty of books out
there on other free/OS software, especially by PACKT Publishing, would
be great to see some more QGIS/PyQGIS materials out there (at least 250
pages, not just a white paper in disguise as a slender book.)

OK, so the big selling point I keep reading is that one can use python
to write scripts, automate processes, write plugins, even a nice new
python console, but there is no api docs for python? That seems very
strange! Again, looks like Gary's upcoming book may fill the void. 

The Introduction in the PyQGIS Cookbook for 2.0 states: "There is a
complete QGIS API reference that documents the classes from the QGIS
libraries. Pythonic QGIS API is nearly identical to the API in C++." So
I click the link but nothing tells me if am looking at the python api or
the cpp api. Users will not care about the cpp api, we just want to know
how to do all this cool python stuff. If it becomes a hassle or takes to
long to figure out (people have clients, budgets, deadlines), then they
will get turned off and go back to ArcGIS where everything is explained
plainly nice and neatly. ESRI made a HUGE, monumental mistake when it
first released ArcObjects with miniscule documentation. Loads of people
were fuming. Took them 10 years to get things right again and thank
goodness they went on the python path. A very talented programmer I work
with here told me that it is well known programmers don't make the best
writers. Just absolutely have to make user-friendly documentation about
your product, especially the api you keep talking about.

David Chrest

-----Original Message-----
From: Richard Duivenvoorde [mailto:rdmailings at duif.net] 
Sent: Friday, October 11, 2013 5:00 PM
To: Chrest, David; qgis-user at lists.osgeo.org
Subject: Re: [Qgis-user] PyQGIS book in the works? Easier to understand
online API Documentation?

On 11-10-13 22:34, Chrest, David wrote:
> Are there plans for a detailed, written in a  you-don't-have-to-be 
> an-experienced-programmer kind of way book that helps explain PyQGIS 
> and how to use it?

I know Gary has plans: http://pyqgis.com/book/availability/

> Python Scripting for ArcGIS by ..
> Programming ArcGIS 10.1 with Python ..

You are not being paid by them or esri are you ;-)

> friendly. Looks like it is written for someone who knows C++. See 
> http://qgis.org/api/classQgisInterface.html. What in world are Public

You are actually pointing to cpp API interface. Currently we do not have
separate api docs for python.
I know Victor has been busy updating the Python cookbook:
http://www.qgis.org/en/docs/pyqgis_developer_cookbook/index.html
That should be more informative for beginners?

BUT I also have to point you to the fact that QGIS is a
community/volunteer driven project, always in need for people wanting to
make the use of QGIS a better experience. Indeed most of us have a
programming background, so please join the community as a documentation
writer (OR pay some experienced doc writers to do it) :-)

Regards,

Richard Duivenvoorde
_______________________________________________
Qgis-user mailing list
Qgis-user at lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/qgis-user

-- 
This message is subject to the CSIR's copyright terms and conditions, e-mail legal notice, and implemented Open Document Format (ODF) standard. 
The full disclaimer details can be found at http://www.csir.co.za/disclaimer.html.

This message has been scanned for viruses and dangerous content by MailScanner, 
and is believed to be clean.

Please consider the environment before printing this email.




-- 
This message is subject to the CSIR's copyright terms and conditions, e-mail legal notice, and implemented Open Document Format (ODF) standard. 
The full disclaimer details can be found at http://www.csir.co.za/disclaimer.html.

This message has been scanned for viruses and dangerous content by MailScanner, 
and is believed to be clean.

Please consider the environment before printing this email.