Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?
Derek, No not negative at all, I appreciate the feedback and suspected the reasoning you explain below. Yes, E$RI (or shall I say E$RI) definitely has mucho dinero to crank out documentation. (Though, they did a horrible job when ArcObjects first came out). Yes, writing sure is time consuming! I work at a non-profit government research contractor where all work is project based, billable hours. They won't exactly let me spend weeks on learning QGIS and documenting (though, that would be a dream job!). I am very impressed with QGIS 2.0 and the documentation that already exists. User Guide, Cookbook, The QGIS Training Manual (1.8) book by locate press, Gary Sherman's Geospatial Desktop book (it's what got me sucked into this OSGIS thing last spring), the searchable email lists, gis stackexchange, other tutorials on the web, blogs, etc. I just think that an important missing component is PyQGIS documentation, but looks like Garry's upcoming book will fill that gap. There was even a recent post of a user saying about QgsLabel, ... documentation is missing or obscure... I like your quote about Linux, but I cannot believe nobody cares about the popularity of QGIS and doesn't care about people liking it and it's ease of use. Then why all the press? Why did Tim Sutton show the world wide users map in his FOSS4GEO presentation? Why the recent comment of a user telling us how impressed his audience was after showing off QGIS? Programmers must care somewhat about how their creation is being used and what others think about it, especially from users who are not programmers, which is the category many GIS professionals fall into. So in this case programmers are not really creating something just for other programmers to use exclusively, they have created something that is used by folks with many different backgrounds. The audience of these non-programmer users is there by default. Saw that a city's government was going to start using QGIS, they are not all programmers. QGIS is seeping into the mainstream and programmers must care and be happy to see this me asure of success. David -Original Message- From: Derek Hohls [mailto:dho...@csir.co.za] Sent: Monday, October 14, 2013 6:16 AM To: qgis-user@lists.osgeo.org; Chrest, David Subject: Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation? 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
Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?
But the logical in FOSS is to have a community that learns and helps to learn. While Linux may be described as someone have cited before, that's certainly not what Linux really is, because some Linux distros have customers, have responsabilities to the bottom line, some Linux distros are pretty popular and globally widespread (maybe not in desktop), some Linux distros make (a lot of) money, etc. My point is that Linux is much more than those propositions even when they may be true, QGIS is similar. On the other hand QGIS 2.0 is a very recent stable version with lots of changes, as we all know, documentation may take some time in FOSS when there's not enough human resources. I wish I could make documentation like this, but I really just can read and try to understand python code. I'm needing a good Python for QGIS from scratch documentation for human beings (kinda Linux for human beings from scratch, KISS monster). Anyway, I can't go back to ESRI. Only once in my time working with GIS (almost 5 years) had access to a license, but I had to use extensions and it was impossible to keep up with ERI and found an introductory training course on FOSS GIS and took it. Still needing pyQGIS and waiting to be a better contributor. 2013/10/15 Chrest, David dav...@rti.org Derek, No not negative at all, I appreciate the feedback and suspected the reasoning you explain below. Yes, E$RI (or shall I say E$RI) definitely has mucho dinero to crank out documentation. (Though, they did a horrible job when ArcObjects first came out). Yes, writing sure is time consuming! I work at a non-profit government research contractor where all work is project based, billable hours. They won't exactly let me spend weeks on learning QGIS and documenting (though, that would be a dream job!). I am very impressed with QGIS 2.0 and the documentation that already exists. User Guide, Cookbook, The QGIS Training Manual (1.8) book by locate press, Gary Sherman's Geospatial Desktop book (it's what got me sucked into this OSGIS thing last spring), the searchable email lists, gis stackexchange, other tutorials on the web, blogs, etc. I just think that an important missing component is PyQGIS documentation, but looks like Garry's upcoming book will fill that gap. There was even a recent post of a user saying about QgsLabel, ... documentation is missing or obscure... I like your quote about Linux, but I cannot believe nobody cares about the popularity of QGIS and doesn't care about people liking it and it's ease of use. Then why all the press? Why did Tim Sutton show the world wide users map in his FOSS4GEO presentation? Why the recent comment of a user telling us how impressed his audience was after showing off QGIS? Programmers must care somewhat about how their creation is being used and what others think about it, especially from users who are not programmers, which is the category many GIS professionals fall into. So in this case programmers are not really creating something just for other programmers to use exclusively, they have created something that is used by folks with many different backgrounds. The audience of these non-programmer users is there by default. Saw that a city's government was going to start using QGIS, they are not all programmers. QGIS is seeping into the mainstream and programmers must care and be happy to see this me asure of success. David -Original Message- From: Derek Hohls [mailto:dho...@csir.co.za] Sent: Monday, October 14, 2013 6:16 AM To: qgis-user@lists.osgeo.org; Chrest, David Subject: Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation? 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
Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?
The PyQGIS Cookbook can, of course, be improved, and is far from complete, but I would say it is already good enough. One of the most interesting things about QGIS is the large amount of different plugins available, and most of them have been developed by people that are not core devs. I guess the cookbook has been their main source of information when learning how to develop plugins, so I think it is already a very valuable resource, and useful for people to learn how to write a plugin, assuming they have no previous experience in QGIS What are you exactly missing in the cookbok? Feel free to propose ideas or point out missing contents/sections, so we can work on them. Thanks! 2013/10/15 Yasser Said Lopez de Olmos Reyes biolyas...@gmail.com: But the logical in FOSS is to have a community that learns and helps to learn. While Linux may be described as someone have cited before, that's certainly not what Linux really is, because some Linux distros have customers, have responsabilities to the bottom line, some Linux distros are pretty popular and globally widespread (maybe not in desktop), some Linux distros make (a lot of) money, etc. My point is that Linux is much more than those propositions even when they may be true, QGIS is similar. On the other hand QGIS 2.0 is a very recent stable version with lots of changes, as we all know, documentation may take some time in FOSS when there's not enough human resources. I wish I could make documentation like this, but I really just can read and try to understand python code. I'm needing a good Python for QGIS from scratch documentation for human beings (kinda Linux for human beings from scratch, KISS monster). Anyway, I can't go back to ESRI. Only once in my time working with GIS (almost 5 years) had access to a license, but I had to use extensions and it was impossible to keep up with ERI and found an introductory training course on FOSS GIS and took it. Still needing pyQGIS and waiting to be a better contributor. 2013/10/15 Chrest, David dav...@rti.org Derek, No not negative at all, I appreciate the feedback and suspected the reasoning you explain below. Yes, E$RI (or shall I say E$RI) definitely has mucho dinero to crank out documentation. (Though, they did a horrible job when ArcObjects first came out). Yes, writing sure is time consuming! I work at a non-profit government research contractor where all work is project based, billable hours. They won't exactly let me spend weeks on learning QGIS and documenting (though, that would be a dream job!). I am very impressed with QGIS 2.0 and the documentation that already exists. User Guide, Cookbook, The QGIS Training Manual (1.8) book by locate press, Gary Sherman's Geospatial Desktop book (it's what got me sucked into this OSGIS thing last spring), the searchable email lists, gis stackexchange, other tutorials on the web, blogs, etc. I just think that an important missing component is PyQGIS documentation, but looks like Garry's upcoming book will fill that gap. There was even a recent post of a user saying about QgsLabel, ... documentation is missing or obscure... I like your quote about Linux, but I cannot believe nobody cares about the popularity of QGIS and doesn't care about people liking it and it's ease of use. Then why all the press? Why did Tim Sutton show the world wide users map in his FOSS4GEO presentation? Why the recent comment of a user telling us how impressed his audience was after showing off QGIS? Programmers must care somewhat about how their creation is being used and what others think about it, especially from users who are not programmers, which is the category many GIS professionals fall into. So in this case programmers are not really creating something just for other programmers to use exclusively, they have created something that is used by folks with many different backgrounds. The audience of these non-programmer users is there by default. Saw that a city's government was going to start using QGIS, they are not all programmers. QGIS is seeping into the mainstream and programmers must care and be happy to see this me asure of success. David -Original Message- From: Derek Hohls [mailto:dho...@csir.co.za] Sent: Monday, October 14, 2013 6:16 AM To: qgis-user@lists.osgeo.org; Chrest, David Subject: Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation? 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
Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?
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:rdmaili...@duif.net] Sent: Friday, October 11, 2013 5:00 PM To: Chrest, David; qgis-user@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
[Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?
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? Something most folks new to QGIS and not necessarily with a programming background (remember, never assume all GIS folks are deep into programming) could understand. Something with the big picture, loads of example, modules, functions, and classes explained? Lots of details about how to write plugins? At least 300 pages. Python Scripting for ArcGIS by Paul A. Zanbergen is an excellent book and knows its audience well (knows not all GIS folks are also experienced programmers, the two are very separate). How about a PyQGIS book like this? All there is right now is the PyQGIS cook book which is pretty slim and I think assumes too much that everyone is a programmer. Programming ArcGIS 10.1 with Python Cookbook by Erick Pimpler is great. So is A Python Primer for ArcGIS by Nathan Jennings. Seems like a obvious need for a good, large PyQGIS book by Packt Publishing, something about three times as thick as Anita Graser's book. Also, to a QGIS newbie, especially to someone who has enjoyed the extremely easy to understand ArcPy documentation from ESRI, the online QGIS API Documentation is incredibly confusing and not very user friendly. Looks like it is written for someone who knows C++. See http://qgis.org/api/classQgisInterface.html. What in world are Public Slots (aren't these just python functions?), virtual Qaction, virtual void, virtual bool, Signals, Public Member functions? What the heck does Constructor Destructor Documentation mean? Member Function Documentation? [pure virtual slot]? Loads of things listed in their own box that don't really tell me anything. What's with ::? Coworker told me it is C++ syntax. What is a .h file? .cpp file? Again, coworker who is programmer told me about these C++ type files. It all seems very messy and does not tell me what I need to know. Can something more organized, such as categorized groupings of functions and classes with a simple summary, discussion, usage syntax (that really needs to be simplified to plain English), parameter list with explanation and data type for each, then some examples? Check out the online ArcPy help page for the ExportToPDF function: http://resources.arcgis.com/en/help/main/10.1/#/ExportToPDF/00s30027 00/. Everything there is explained well, tells me how to use it, what it does, lists parameters, simple types, and code examples. No Public Slots or virtual bool here, just straightforward lists of types like string, boolean, integer. See how all the ArcPy classes and functions are organized into categories like Cursors, Fields, Geometry, Listing data, Raster, etc., so a user can go straight to what they need. Can something like this be created for PyQGIS? You will get a lot more people on board with QGIS this way. David David Chrest Research GIS Analyst RTI International 3040 Cornwallis Rd, PO Box 12194 Research Triangle Park, NC 27709-2194 ___ Qgis-user mailing list Qgis-user@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/qgis-user
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@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/qgis-user
Re: [Qgis-user] PyQGIS book in the works? Easier to understand online API Documentation?
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:rdmaili...@duif.net] Sent: Friday, October 11, 2013 5:00 PM To: Chrest, David; qgis-user@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@lists.osgeo.org http://lists.osgeo.org/mailman/listinfo/qgis-user
