Comprehensive, unified documentation

[raulgd]

Hi, as y'all may notice, I'm new to POCO, from what I've seen, the features, modules, etc. It's exactly what I've been looking for, actually the deal breaker that makes me try to use POCO instead of Qt for a server app I need to build, is the crypto module and the use of ISO C++, my RPC libraries make extensive use of STL types (vectors, lists and the like) and on Qt everytime I need to send or receive data, I have to convert between standard and Qt classes, which gives me quite an overhead.

What I want to request as a newbie is more comprehensive documentation, there is plenty of info, but everything is scattered between pdf slides (which are way too short for any practical use of the feature in an app), the user guide which also seem more like ramblings around all of POCO features, and the reference that, it is complete, but still just reference and not for actual learning, and of course what is needed the most, is the use of the whole module libraries as a complete solution on an application.

I'm not asking if someone else writes it, I know everybody is really busy on their own projects (as do I), but If someone is willing to help me learn in a more pragmatic way how to use POCO, I'll write the complete document, even as a complete POCO developer's guide book (I started my developer experience in writing software technical documentation) from a C++ developer's point of view new to POCO, and the document's focus would be to make the C++ developer an expert in POCO modules.

To fulfill the request, all I would ask is any veteran POCO developer, or even someone from Applied Informatics if they are willing, to help me in my quest, I'll learn POCO as we go on, write chapter by chapter from introduction, to each and every module, and at the end of every chapter, post the results for everyone to proofread. It would be awesome to publish this PDF as a creative commons complete guide of POCO book.

Thanks

[guenter]

Hi Raul,

thank you for your suggestion. Writing a book on POCO is something we (Alex and I) have had in mind for some time now. But we've never had the time to do it. So, it would be really great if we could get the book project going. Your contribution would be much appreciated, both from the perspective that you can give valuable input from the point of view of a beginner with POCO, and from the perspective of a technical writer. We already have some material to contribute (I started a book on C++ cross-platform programming a few years ago, but never finished it), and there are various other articles and papers that we can use as well.

So I'd suggest we join forces and get this project going. Do you have any ideas what to include in the book? I'm thinking of a "cookbook"-style book that starts with some general background information (how to build, first steps on Windows, Linux, OS X, etc.) and then cover the features of the different libraries by building sample applications.
Another resource that may be useful are the sample programs from Setsu (see his forum post: viewtopic.php?f=12&t=4718&hilit=poco+fanatic). He also has a website where he writes articles about POCO, albeit in Japanese. Maybe we can get him on board as well.

Let's get this started!

[raulgd]

Hi Guenter! thanks for the response!
It´s great to see that you guys are on board with this.
Yeah, actually, I started planning the TOC (Table of Contents), and yeah, I think the best way to write this book is with a mix of a cookbook and a developer's guide.
The book could be divided in three parts:
Part 1: POCO C++ Open Source
Part 2: POCO C++ addons
Part 3: Third Party integration

Pretty much, the whole book would revolve around one exercise (like a cookbook, would be very practical, but like a developer´s guide, instead of isolated solutions, it would be one full solution that would get more robust as you advance on every chapter so it gives you a big picture of the complete POCO solution), this exercise would be a client-server solution that would make use of the complete POCO environment, using from foundation to the commercial addons from appinf, and at the end, use a third party library (like Qt and ICE) to close the book with embedded (in this case, an iPhone/iPad version of the client in the exercise).

We would have an introduction in the book, and layout the proposal, requirements and architecture for the exercise that, at the end of the book, would be the resulting product with a server, a web client in PHP on a browser, a desktop client (using Qt and ICE) and a mobile client (using an iPhone or iPad).

So, part 1 would be composed of building POCO full (with OpenSSL and MySQL) because the exercise in the book would make use of both so we cover the complete library, also it would cover each and every module of the open source library like foundation, util, Data, XML, ZIP, crypto, etc. and also in each and every chapter, we would be adding the needed functionality to the exercise product.

In part 2, we would place examples of how to add the commercial part of POCO, use remoting, use fast infoset to increase remoting performance, making the server modular with OSP, adding zeroconf so clients autodetect the server on a network, etc. That way, the community also learns about the commercial offerings that really help you exploit POCO even further.

And part 3, it would show how POCO is not an isolated library, and that you can use it with other frameworks to build even more complete solutions, we could start with building a client in PHP so that it calls services from the server and renders the results in a browser, then giving the client from previous chapters a GUI using Qt, another chapter add multilanguage communication capabilities between client and server using ZeroC ICE, and close with making the client run on an embedded device with a GUI using iOS API.

What do you guys think? do you like it? so we start building the TOC based on this.

I know it sounds like a lot of work and that it's ambitious, but hey, if we're gonna do this, we might as well do it right and go the whole nine yards.

[fbraem]

If this is going to happen, I'm always interested in revising, testing examples, and even maybe write some text ... Let me know when and how I can help.
I think the documentation on http://pocoproject.org/documentation/index.html is already a good starting point for a cookbook.

Franky

[agilevic]

My three chief problems with C++ are that it is:

1) Too easy to use incorrectly,
2) Harder (than Java) to write portable programs
3) Much harder to manage projects (build system, test, continuous integration, refactoring, etc.)

You have done remarkable job writing portable C++ code and your libraries make it easier to use C++ correctly. You must have also obviously mastered the software project management in C++ because your sources will build under any system I care to know about and then some.

I would like to suggest that you write in your book about best of breed developer's tools and best practices how to use them in an agile way for C++ development. If I have to pick one thing that makes me avoid C++ that would be a nightmare of editing Makefiles to deal with linker dependencies, circular dependencies in headers, include paths etc., etc.

If the above is not in scope for your book, I would much appreciate book/blog/white paper recommendations on this topic.

[SalvorHardin]

Hi Guenter! thanks for the response!
So, part 1 would be composed of building POCO full (with OpenSSL and MySQL) because the exercise in the book would make use of both so we cover the complete library, also it would cover each and every module of the open source library like foundation, util, Data, XML, ZIP, crypto, etc. and also in each and every chapter, we would be adding the needed functionality to the exercise product.

Great idea, about building the full POCO version.

I have some ideas:
1. using sqlite instead of MySQL, etc. would eliminate the need to install a 3rd-party RDBMS (some users won't have admin rights on Windows or sudo, etc.)
2. if you want a comprehensive example project (in addition to smaller cookbook examples), then a web application would be nice. For example, a todo server written in POCO that can be accessed from a browser. The ToDoList open source project from AbstractSpoon might provide some good ideas on using XML for todo data.

[setsu]

Another resource that may be useful are the sample programs from Setsu (see his forum post: viewtopic.php?f=12&t=4718&hilit=poco+fanatic). He also has a website where he writes articles about POCO, albeit in Japanese. Maybe we can get him on board as well.

I'd like to join the POCO Cookbook project.
Sample codes in my web, and subversion http://www.assembla.com/code/poco_fanatic/subversion/nodes, can be used for them, and I can translate the book into Japanese version.

[alex]

To fulfill the request, all I would ask is any veteran POCO developer, or even someone from Applied Informatics if they are willing, to help me in my quest, I'll learn POCO as we go on, write chapter by chapter from introduction, to each and every module, and at the end of every chapter, post the results for everyone to proofread. It would be awesome to publish this PDF as a creative commons complete guide of POCO boo

I suggest you make use of the help offered in the forum and lead this project to fruition. It would be a good thing to have a book. I've had to lower my project involvement in the last couple of years but I will be back as soon as the circumstances permit. The biggest thing I have to tackle is database support, so whenever that occurs I could contribute a chapter or two on that portion to the project.

[guenter]

Thanks a lot for your offers to contribute to the book!
As the next step, we should do some planning. Specifically, come up with a preliminary book structure and table of contents and distribute some work (who will work on which chapters, etc.).
Should I set up a special mailing list for the book for collaboration? I guess that would be the easiest way to handle this.

[raulgd]

Thanks a lot for your offers to contribute to the book!
As the next step, we should do some planning. Specifically, come up with a preliminary book structure and table of contents and distribute some work (who will work on which chapters, etc.).
Should I set up a special mailing list for the book for collaboration? I guess that would be the easiest way to handle this.

Cool! it's nice to see we have a lot of contributors!
I would prefer a seperate board on the forum for the book, as it's easier to have feedback from the whole community, and you get the extra of having the forum search, quotes, code, etc etc. (Check out the Manning Publishing MEAP books, the authors use a MEAP forum for feedback and it works great, I've contributed there)

Also, you could setup something on the forum so we attach bigger files, 'cause for example, I tried to upload a mod I did for building the SQLite module with SQLCipher so that the database files are encrypted, and it was about a 1MB zip archive, and the forum didn't allow me to upload the file.