Missing developer documentation

marebe1602 commented 11 years ago

This might be the wrong place, because it is not a bug within PHP-Code, but it definitely is an issue! I really like developing contao web sites, but a good developer documentation would save a lot of time and the resulting code would be much better. I know, some of the core developers say "just inspect the code to see how it's done", but if you think that way, you might ignore the following side-effects of a missing documentation:

very often, the developer choses the CMS system to be used, so it's important that he likes developing with it
the easier it is to get into contao, the more good extensions will be out there
if there are lots of good extensions, popularity of contao will grow further
If you have a small budget for a site to be developed, you don't want to spend hours on searching the core source code. So you might choose the quick and dirty way. And this is a shame, because most of your hard "core" work won't be used.

Please invest some time to set up one "Developer Handbook PDF"! I really like the spots of source code, I've seen, but sometimes I just don't have the time to crawl the classes for the "best-practice-solution".

Martin

Zeromax commented 11 years ago

+1

brandbrilliance commented 11 years ago

LOL.

katgirl commented 11 years ago

Ofizelle Seiten:

https://contao.org/de/manual/3.1/data-container-arrays.html https://contao.org/de/manual/3.1/customizing-contao.html https://contao.org/de/manual/3.1/extension-repository.html

API:

http://api.contao.org/

Videos:

http://www.youtube.com/user/bit3ug/videos

Tagebuch http://de.contaowiki.org/Kategorie:Tagebuch_einer_Extension-Entwicklung

brandbrilliance commented 11 years ago

Lol. /de/ you mean /en/ - another reason Contao hasn't taken off like it could have... I spend a lot of time deciphering Google German Translate... In both Wordpress and Mootools all the code have fantastic examples on how to use it, what to watch out for, and what mistakes to avoid. Simply providing a computer rendering of the API is not enough. The learning curve stays high in these cases. You want people to dig in quickly.

katgirl commented 11 years ago

only the movie and diaray are in german

brandbrilliance commented 11 years ago

https://contao.org/en/manual/3.1/customizing-contao.html#adding-custom-fields

The documentation for this section is wrong and outdated. You no longer use database sql files, you don't use DCA without adding the index, SQL, so no one has fixed this since 3.0 release, which is almost 1 year old!

marebe1602 commented 11 years ago

as thyon said, examples would really be great. It doesn't have to be a 250 page documentation, just a few core topics with examples, Dos and Donts. Small enough to keep the effort affordable to keep it up to date. I already found the documentation links, provided in the posts above, but it took me quite some time, too. Following are my proposals for a basic TOC:

DCA overview How to extend an existing FE module How to create a new FE module How to customize existing extensions How to create a new extension (with detailed examples, traps and best practice hints) The Frontend class The Backend class

I really believe, that this could give contao the boost, it deserves and I am not joking at all.

brandbrilliance commented 11 years ago

As the person who has made the most comments on the English community forum to help and guide both newbies and developers (I probably shouldn't be mentioning that, LOL), someone who has dipped into the development side of things by writing extension like Catalog, Gallery, FormAuto, QuickPoll, Invitation, Includes, CE_Wrap, CE_Break, MyFavicon, ZThemeLargeIcons, ZThemeTopTab, Favorites, and being one of the influencers of the core functionality feature list by writing or adding many small but very noticeable features to the Core through the years, I think I'm in a perfect position to second Martin's requests.

I'm just a casual coder (contrary to popular belief) and I've found it very arduous to code, because I, like so many new developers, learn to code through using examples with possible mistakes clearly highlighted. The core has examples like news, calendar, but they are relatively "hardcore" (pardon the pun) and way to daunting for developers to sink their teeth into.

One of the primary arguments to persuade me to become involved, was the great old CD Database example, because in a few paragraphs, easily demonstrated what could be possible with a very minimal amount of coding. I cannot locate that examples anywhere, or something even close to it. There have been some blog posts by other developers, but these are also now missing (or have fallen off the map somewhere).

Perhaps this has just needs more English as I have always maintained. You can just compare the home page for the Community boards for /de and /en to see the big difference. Once an global audience takes a shine to you then you will become more international and a flood of new developers can help out with more refined documentation, examples, etc.

xchs commented 11 years ago

https://contao.org/en/news/migration-of-the-contao-documentation.html

Anyone can contribute to the docs by sending us pull requests. [...] Right now, the documents are still the same as the old online manual (except a few files like the installation chapter) and have to be proof-read and adjusted to Contao 3. We hope for an active community participation.

ghost commented 11 years ago

In my opinion this is a big problem. There are some ressources like the contao-wiki or the github-documentation, but this isn't enough at all. Like thyon mentioned, the tutorial from Kamil Kuzminski for Developing an own module was a (maybe the only) chance for me to dive into the extension-development. On the contao-conference this year, i've heard an interesting discussion about a possible documentation of the Framework. The most people in the room where core-developer, which had the opinion "developer should read through the code, that should be enough". As a bad example(!) they mentioned the php.net. But this is sooo awfully wrong!!! php.net does not give you the 100% right solution for your problem, but it gives you always an approach on which you can set up.

As a Developer, i will choose a well documented System, if i know that i have to develop extensions. Why should i choose Contao as long as i have a lot of alternatives. And i think that is the main reason for the fact that Contao is loved by frontend-developers and webdesigners but not by Developers. I love it too, as long as i have a standard-website.

One example: I wanted to implement a save-callback-function in a custom module. I've spend over an hour to get out which parameter this callback is awaiting. I've found the answer in the DMA-Elementgenerator extension. Too funny, isn't it...? It's not!

+1 for the Developer Handbook.

brandbrilliance commented 11 years ago

Yes, only the HOOKS are documented with examples, the rest is hit/miss.

Checkout the level that Wordpress provides: http://codex.wordpress.org/The_Loop

This is fantastic work they have done. It's mostly because of this that I'm doing most of my new websites in Wordpress, rather than Contao :-(

Thielo commented 11 years ago

I would also appreciate it.

leofeyer commented 11 years ago

Closing this ticket because it does not belong here. However, I also feel like everything has been said. The Contao manual is an open project on GitHub and anyone can (and is invited to) contribute.

contao / core

Missing developer documentation #6012