about bugs and documentation

Hi guys!

I’m fairly new to modx and I’m loving it. currently i’m implementing a pretty big project, and there are a couple of things I want to put up for discussion. Not sure this is the right place but feel free to move it

Although I love programming in modx, it is not bug-free. I can file bugs, but most of the time I don’t have the time to wait for a fix. Secondly, I don’t mind fixing them myself but I don’t want to end up with modified core/snippets etc so that I end up with problems when upgrading. Is there any way I can help by fixing the bugs I find?

Secondly someone needs to come up with organized documentation. It needs to be clear what goes where. I’m coming from Typo3 and history has shown there that when documentation grows and it is not clear what goes where, it turns into a complete mess.
1. I would suggest getting rid of the non-english languages on the wiki because I already found helpful documentation in german which is not there in english. Everyone knows english at least to some extend.
2. The documentation on modxcms.com is pretty good to get one started, although one soon wants more. Maybe that needs to be on the wiki, with direct links to the wiki.
3. I think modx needs a standardized API documentation system.
4. The wiki can work well but right now the organization on the wiki-frontpage provides for a lot of ambiguity. for example, where does a FAQ about a snippet go, in ’faq’ or in ’snippet’? people will miss information. Same for tips & tricks. Also, some tutorials/help to build a module or a snippet that show the most common functions would be nice. It would be what I would expect to be on top when I click ’snippet’
5. get a more straightforward forum-search option; the google search searches the whole site and all languages. That’s not very helpful. I would like to search the forum, and just the english part.
6. sometimes there is documentation in a snippet and it happened to me that I’ve been looking everywhere on this site for the docs and couldn’t find them. eForm has this problem (the docs that come with it are very good tho). I would move the docs to the wiki and only there.

well, those are my 2 cents I would be happy to participate in order to make this CMS even better.

Participation is always welcome, however I personally (although as a typical American English is my only language) find point #1 problematic. MODx is for anybody who wants to use it, not just those fluent in an arbitrarily designated language. I don’t mean to start a war here, just to indicate that I don’t expect to ever see that attitude espoused by the MODx team.

There are two large issues with documentation for MODx. One is that development of MODx and its main snippets progress at such a rate that it is difficult indeed to keep up with it. The other is that no two sites are alike; no two developers want to do exactly the same thing. What provides clear, simple documentation for one design does not address the requirements of another. That is the two-edged sword of the power and flexibility of MODx.

I completely disagree with #1 as well. Other languages have lots of talented developers who in fact are not fluent in English at all.

As far as fixing bugs and "not having a hacked core" in an ideal world every bug report would be accompanied by bugfix code!

We all have different way of learning.

As far as I am concerned, I see documentation as a "starting point". Some need extensive doc to be able to work, I kind of like to learn along as I go and I find the forum is so fast and helpful I hardly ever missed any documentation. But then we should probably talk about documentations, plural : user doc, designer doc and developper doc. I am no developper, hence my limited perspective.

This being said, things could sure improve and the hardest part of all is keeping information together. The wiki has been a great step up, but lots of gems are scattered over the forum. I confess I almost never take time to have those great piece of information re-written into a documentation (this is not as trivial as it might seem, btw). I list those threads into the FAQ at the french boards, which is the quick and dirty way to keep track and share things.

Like most contributors, I have quite a bit of work and I can strech time indefinitely. I choose to help at the forum and experience with MODx rather than write, I am afraid and I am likely to do so until MODx development slows down a bit

As Susan elegantly pointed out, "the two-edged sword of the power and flexibility of MODx" makes it hard to document every way to achieve something with MODx. You always find new way to use tools and resources, along the way. I am not saying there is no need for documentation or no room for improvement, simply that the context makes it hard to achieve in short term...

As for bugs, well I don’t think any app is bug free
And I am pretty happy with MODx, especially since the really annoying bugs are fixed pretty fast IMHO !
I have never been stuck long with MODx and that’s what matters (to me, at least).

hi guys thanks for the insights

regarding the bugs, of course no application is bug free but lets put it like this: sometimes I’m fixing bugs myself because I need a fix fast. This is no problem, except that it’s a bummer that it provides me with upgrading problems, or the fact that someone else (who’s fixing bugs in the modx cvs) needs to do the exact same piece of coding. Anyway I’ll take rtrash’s advice into account and post the fix with the bugs i’m filing, that’s a good start.

How is the development of modx organized anyway? Can anyone participate fixing bugs etcetera? What if I wanted to help developing?

I can imagine your points of view regarding #1. I think my main point was that we could use more documentation like http://www.modxcms.com/documentation.html, especially about programming snippets etcetera. An example that shows the document parser’s execution order, parses some chunks, uses some events, etc would be fairly general purpose and would help a lot of people I think.

Its great to see that people are actively working on it though and I do see the problem that it is complicated. This post was merely a call for a well documented plan on how documentation is going to be organized for the future. Just remember the millions of times we all have used php.net to find the specification of a particular function and the comments/examples below that. Crucial information should be in the api, not in the forums

Quote from: erikp at Aug 31, 2007, 03:10 AM

This is no problem, except that it’s a bummer that it provides me with upgrading problems, or the fact that someone else (who’s fixing bugs in the modx cvs) needs to do the exact same piece of coding. Anyway I’ll take rtrash’s advice into account and post the fix with the bugs i’m filing, that’s a good start.

This is a valid point and that’s why Ryan asks you to post the fix along with the bug report (or as a comment to a bug already reported).
Bugs are managed with FlySpray, not the forums it would be impossible to work that way.

That’s why we encourage systematic bug reports into FlySpray. Maybe this is not clear enough and we should provide more insight about this on the main modxcms.com website (redesign and new content is work in progress).

Quote from: erikp

How is the development of modx organized anyway? Can anyone participate fixing bugs etcetera? What if I wanted to help developing?

Anyone can participate in fixing bugs, just submit bug reports and add fixes into FlySpray, this will be taken into account. Many people who have done so ended up in the Testing & QA team In fact, that’s the first step integrating the MODx team. This goes a bit the same for joining the development team : you write code, create new MODx resources (snippets, plugins, modules) and you get spotted and co-opted into the dev team.

Quote from: erikp

I can imagine your points of view regarding #1. I think my main point was that we could use more documentation like http://www.modxcms.com/documentation.html, especially about programming snippets etcetera. An example that shows the document parser’s execution order, parses some chunks, uses some events, etc would be fairly general purpose and would help a lot of people I think.

Its great to see that people are actively working on it though and I do see the problem that it is complicated. This post was merely a call for a well documented plan on how documentation is going to be organized for the future. Just remember the millions of times we all have used php.net to find the specification of a particular function and the comments/examples below that. Crucial information should be in the api, not in the forums

As I said, I don’t really grasp what the state of the API’s doc is, since I am no coder but I sure undertstand your point of view. Reaching the level of php.net might be a very hard thing to achieve though ! Maybe when we have a wide community of MODx developper this will happen...

Quote from: davidm at Aug 31, 2007, 05:07 AM

Quote from: erikp

How is the development of modx organized anyway? Can anyone participate fixing bugs etcetera? What if I wanted to help developing?

Anyone can participate in fixing bugs, just submit bug reports and add fixes into FlySpray, this will be taken into account. Many people who have done so ended up in the Testing & QA team In fact, that’s the first step integrating the MODx team. This goes a bit the same for joining the development team : you write code, create new MODx resources (snippets, plugins, modules) and you get spotted and co-opted into the dev team.

That is one way to get on the team. Of course, if you are interested in collaborating on core development, feel free to PM me directly and discuss bypassing the above scenario. We’re always looking for good developers to help extend the team.

Quote from: davidm at Aug 31, 2007, 05:07 AM

Quote from: erikp

Its great to see that people are actively working on it though and I do see the problem that it is complicated. This post was merely a call for a well documented plan on how documentation is going to be organized for the future. Just remember the millions of times we all have used php.net to find the specification of a particular function and the comments/examples below that. Crucial information should be in the api, not in the forums

As I said, I don’t really grasp what the state of the API’s doc is, since I am no coder but I sure undertstand your point of view. Reaching the level of php.net might be a very hard thing to achieve though ! Maybe when we have a wide community of MODx developper this will happen...

The core rewrite for 0.9.7 will include full API documentation, produced by phpDocumentor. The plan is to author tutorials and other supplemental documentation linked into this generated API documentation in DocBook format. In this way, we can easily produce HTML, PDF, CHM, and other documentation formats from the same documentation source.

I’m in the process of finalizing some key infrastructure changes with regards to MODx development (SVN and Trac are moving, and we’re adding Fisheye/Crucible). We’re going to make Trac much more integral to the development team once this move is completed, making it the official development wiki. Then we’ll be looking at implementing a continuous peer code review process using Crucible. Unit testing, continuous automated builds, and more are also on my list of things-to-do, once 0.9.7 is released.

Some good points, I think, by the OP.

Davidm’s point about the speed of change of MODx discouraging some solutions is the key here. I have thought several times about contributing to the documentation, but it’s hard to get cranked up to write docs for 0.9.6 when 0.9.7 is due out and 1.0 is in the pipeline.

Another issue is the generally cordial atmosphere at MODx central. It’s one of the most refreshing things about this place (especially when compared with some other CMS sites), but I think some people hesitate to re-write other people’s docs for fear of stepping on toes. There are some snippet docs here that are fantastic, but others that I would throw out and re-write from scratch. Being a relatively new user of MODx, I’d feel very uncomfortable doing so unless someone asked me first.

Another factor that you don’t hear much about it the semi-intentional growth factor inhibition initiative. If all the docs were perfectly organized and written so that anyone at all could be successful in doing what they desire with MODx, the growth of the MODx community would increase exponentially and there is some fear that the people who actually get the work done around here (this list doesn’t include me, at present) might be overwhelmed with support requests.

I’m sure it’s tough to balance this fear against the fact that less-than-perfect documentation also leads to a large volume of support requests.

Bob

BobRay,

Never hesitate to improve on what exists documentation-wise, even if it needs to be published as a "supplemental" or "alternate" bit of documentation. Most MODx contributors don’t have toes, and welcome any improvements.