"…mais ce serait peut-être l'une des plus grandes opportunités manquées de notre époque si le logiciel libre ne libérait rien d'autre que du code…"

Archive for the ‘Django’ Category

Python : documentation technique de projets logiciels : un article de Jacob Kaplan-Moss (partie 1) / Django / sphinx

Posted by patrick sur novembre 12, 2009

Source: http://jacobian.org/writing/great-documentation/what-to-write/

Voici quelques extraits intéressants:

I love Django’s documentation. It clocks in at about 700 pages printed, and most of it is clear, concise, and helpful. I think Django’s among the best documented open source projects, and nothing makes me prouder.


Today I’ll discuss the different forms technical documentation can take, and where to focus your efforts.

 

Tutorials

Good tutorials are a must as they’re usually the first thing someone sees when trying out a new piece of tech. First impressions are incredibly important: that rush of success as you work through a good tutorial will likely color your future opinions about the project….Be quick. At some conference or another I heard someone — I think it was Kathy Sierra — say that, as a rule of thumb, a new user should be able to experience success within thirty minutes…

Topical guides

This is the meat of your documentation. Once somebody’s learned (from a tutorial) the high-level concepts, they’re going to need to dive into the details of some area or another. Any documentation worth its salt is going to have a whole bunch of these — Django’s got about 35 different topical guides, covering each conceptual area (e.g. models, sessions, testing, etc.)…The main goal for topical coverage should be comprehensiveness. The reader ought to come away from a close read feeling very comfortable with the topic in question. They should feel that they know the vast majority of the possible options, and more importantly they should understand how all the concepts fit together.

Unfortunately there aren’t a lot of projects that do these very well. Most have reasonable tutorials, many have okay-to-good reference material, but most seem to leave the topical guides to books.

 

Reference

Finally, you need complete reference for all the public APIs your project provides. These should be designed for those who already know how to use some API, but need to look up the exact arguments some function takes, or how a particular setting influences behavior, etc…It’s important to point out that reference material is not in any way a substitute for good tutorials and guides!..Think of guides and reference as partners: guides give you the “why,” and reference gives you the “how.”

It’s really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material.

Don’t.

Auto-generated documentation is almost worthless. At best it’s a slightly improved version of simply browsing through the source, but most of the time it’s easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a “documentation” link and see auto-generated documentation.

There’s no substitute for documentation written, organized, and edited by hand.

I’ll even go further and say that auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation, thus putting off actually writing good reference by hand. If you don’t have documentation just admit to it. Maybe a volunteer will offer to write some! But don’t lie and give me that auto-documentation crap.

A voir

–  http://www.djangoproject.com/ (‘Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.’)

http://www.django-fr.org/ (‘Django est un framework écrit en Python. Puissant, il est utilisé par des organisations comme la Nasa, le Washington Times et a servi de base à Google App Engine. Mais Django est aussi adapté si vous n’êtes pas une multinationale ou une agence gouvernementale‘)

 

Publicités

Posted in Django, Documentation, python, Python Web Frameworks, Sphinx | Tagué: | Leave a Comment »

Quelques nouvelles d’applications python: Open Object, OpenERP 5.0, Django + Python 2.6 Quick Reference de Richard Gruet

Posted by patrick sur février 11, 2009

Quelques nouvelles intéressantes concernant le développement d’applications python:

http://thisweekindjango.com/callcasts/episode/9/callcast-discussion-corey-oordt-and-opensource/ (‘ A conversation with Corey Oordt discussing the new OpenSource Washington Times project and their forthcoming collection of reusable apps, along with greater goals for becoming a platform for Django newspaper/media applications. Oordt is the Deputy Internet Director for the Washington Times. His small team of Django developers soon plans to make a greater public position in the open source community with their latest opensource.washingtontimes.com project website and their soon to be releases project repository including django-suppertagging (Open Calais integration), django-massmedia, solango, a Django powered trac-like management application, django-clickpass, along with further aspirations for hosting Django sprints, projects, and ideally growing into a platform for hosting Django powered news applications. ‘)

http://thedjangoforum.com/board/ (‘A forum for anyone interested in Django or Python development. Find help for your Django related questions or share your knowledge with developers that are just getting started. Please come take a look’)

http://rgruet.free.fr/#QuickRef (The Python 2.6 Quick Reference is available in HTML and PDF formats. This time I was helped by Josh Stone for the update. As usual, your feedback is welcome (pqr at rgruet.net. Source: http://groups.google.com/group/comp.lang.python.announce/browse_thread/thread/70f000802201af4a/ea354c557bf13bb0?show_docid=ea354c557bf13bb0&pli=1).

http://groups.google.com/group/comp.lang.python.announce/browse_thread/thread/529f43330e4c5ac5 (‘OpenERP 5.0 is out ! Why do I talk about OpenERP on this mailing list ? Because OpenERP is fully developed with Python. That major enhancement of Open ERP can now answer to all the needs of a business. Open ERP V5 not only provides management functions, but also all functionalities necessary to a SMB, like : a process management by modules, a wiki, a webmail, a Business Intelligence (Cube OLAP),  a Document Management System, an eCommerce, an idea box, etc.This new version comes with a full review of the web site giving access to more then 1500 pages of documentations on business management and a reorganization of the community sources build upon the Open Object framework. Free cycles of conferences are planned with the version 5.0 release of Open ERP.
Thanks to its huge community, Open Object produce more then 20 modules a month. The Open Object community it is more then 1000 contributors, 126 development branches in parallel, an average of 400 new functionalities or bugfix per month, one commit every 5 minutes and functional and technical  experts specialized by activity and working in teams.
The rise of Open Object and the diversity of the projects makes it an unmatched framework composed of more then 400 modules installable in a few clicks to cover all kinds of need or to simply start, with a simple module, to answer a simple need. Then, you can install other functionalities to come to a fully integrated and automatized system.
Open ERP v5 is characterized by the appearance of many functionalities far beyond the perimeter of traditional management. One can underline the following innovations:

* An integrated wiki.
* An integrated document management system.
* A Business Intelligence (BI) using a OLAP (Online analytical processing) database.
* An integrated BPM (management of process).
* A web portal for clients and suppliers.
* Improvement of translations (1 translation file by language and module).
* A touchscreen point of sale.
* A full Ajax webmail .
* A shared calendar.
* Plugins for Outlook, OpenOffice, ms. Office, Thunderbird.
* An integrated eCommerce, etc

This new release offers 3 user interfaces :
* the rich application client for a day to day advanced use,
* the web interface allowing a remote access and an easy deployment,
* the QT client that perfectly fits in a KDE environment.

….
The web version of Open ERP includes numerous functions to  modify or create your own application :
* an visual view editor,
* an object editor,
* a workflow (process) editor,
* an Open Office integrated report editor
* a statistics engine (BI cube),
* etc…
URL: http://www.openerp.com
URL: http://www.openobject.com
DOC: http://doc.openerp.com
Screencast: http://www.openerp.tv
LaunchPad Project: http://launchpad.net/openobject‘).

http://freshmeat.net/projects/openerp/?branch_id=77761&release_id=293852 (‘Open ERP is a complete ERP and CRM. The main features are accounting (analytic and financial), production management (MRP), stock management, sales and purchases management, task automation, marketing campaigns, help desk, POS, and more. Technical features include a distributed server, flexible workflows, an object database, a dynamic GUI, an XML-RPC interface, and customizable reports. ‘)

https://launchpad.net/openobject (‘OpenObject is a professional Rapid Application Development framework in Python that allows you to build your applications within a few minutes. This is the main project of all related projects around OpenObject: OpenERP (a complete enterprise management software), OpenObject Server, OpenObject Web Client (the web version of OpenObject applications), OpenObject Application Client, BI (a complete business intelligence application based on openobject), OpenObject Addons (about 300 modules available for OpenObject’s applications), .

  • OpenERP (‘This project contains all packaging scripts to allow you to download and customize openerp instances and create packages which are a selection of modules and projects. These scripts will download all different bazaar projects and link them to create an full openerp system.’)

  • OpenObject Addons
  • OpenObject Business Intelligence (‘OpenObject’s Business Intelligence allows you to build a full featured and flexible reporting environment in a few minutes. It plugs efficiently on OpenObject’s applications but also on most populare databases. You don’t need to waste time building complexe and inflexible shemas: due to his user friendly cube designer, it allows you to build or customize your cube on any application in a few minutes. The datawarehouse structure is then computed and feeded automatically based on an analysis of the queries made by the end-users. OpenObject is the first tool ever made that allows small companies to set up a complete Business Intelligence solution within a few hours. The following animations present you how to we built a complete schema on a new database in a few minutes.’)
  • https://launchpad.net/openobject-client OpenObject Application Client (‘OpenObject is an open source framework based on Python that lets you build your entreprise applications extremely fastly and easily. It includes an ORM, a Workflow engine, several report designers, a MDX engine, a dashboard designer, a module system, an automated migration engine, and much more… Get a web (Ajax) and a rich application with the same code and launch your SaaS offer within minutes thanks to our portal, our webservices interfaces and our 300+ available modules.’)
  • https://launchpad.net/openobject-client-kde KDE OpenObject Client (‘Cross-platform OpenObject Client based on Qt and KDE libraries.’)
  • https://launchpad.net/openobject-client-web (OpenObject Web Client:  The Web client of OpenObject offers a high quality and ergonomy client for OpenObject and OpenERP. It is known to work with all major web browsers available today, including Firefox, IE6, IE7, Safari3 and Opera9. It uses extensively Ajax for a maximum of ergonomy and a minimum of communictation. It includes a calendar view, a workflow designer, a view editor, an object designer, eso.)
  • https://launchpad.net/openobject-doc (Open Object Documentations : This is the project to manage .rst documentations on Open ERP and Open Object. Most documentations must be written in .rst, and we generate the final output using Sphinx.)
  • https://launchpad.net/openobject-server (‘OpenObject Server: ‘)

Posted in 2009, Django, Génie logiciel, logiciel libre, open source, python, Python application development framework, Python Web Frameworks, RAD | Tagué: , , , , , , , | Leave a Comment »