Wikis & Blogs - More Web 2.0 than Forums?

About the online API documentation, would it not be easier to set this up as a Wiki?

I’m relatively new to developing with MODx’s API and I work much better with examples. It took me a good couple of hours to get my head around the differences between getTemplateVar, getTemplateVars, and getTemplateVarOutput. We, as users of MODx, could upload examples to save you guys the hassle?

Just a thought.

I was considering on starting a "developer’s blog" for somewhere to write about the problems I encounter and my solution to them. Forum’s are great, but I think blogs and wikis are little more "Web 2.0".

[EDIT] Thanks Zi for moving this post. Sorry ’bout that. Mind went a bit loopy. [/EDIT]

My personal take on this is that a wiki would be great for documentation but I don’t think it should replace the official documentaiton. I like having "offical documentation" that you know is reliable and hasn’t been edited by someone who doesn’t know what they’re doing. Also, I honestly don’t like using non-MODx solutions as a part of the MODx project unless it’s absolutely necessary. But if someone wanted to steup a separate MODx wiki site I think it would be great.

What I would really like to see is comments on the documentation. The online documentation that I enjoy using more than any other is the PHP.net documentation. I know that the PHP documentation is acurate because it’s done by people who know but the comments still give you a lot of good unofficial input.

I think wikis a great for collaborative writing. The main plus they have over most CMS is :
- revisionning / rollback
- auto TOC generation

I also agree comments on the documentation would be nice, but more in the way some wikis have with "Discussion page". I think it’s better not to clutter the documentation pages themselves.

If we need/want a wiki used with MODx, we can try integrate one, but since MODx will at some point have revisionning/rollback, would it be of interrest ? Not sure... plus the already discussed issue of wiki syntax : some people don’t like them at all... we had the problem with TextBook (Textpattern’s wiki). Contributors, used to Textile, were put off by MediaWiki’s syntax... It does not mean it can not work (see WordPress Codex, which is great), just that context is of the essence when choosing a web application.

But true it’s something that’s very much worth discussing, which indeed has been discussed among the MODx team Can’t vote Yes or No, just say that maybe in MODx’s case it’s not worth having a wiki for we can do it an alternate way.

About the web 2.0 angle, blog and wikis are "trendy", as is AJAX but different tools have different use (it’s deep, isn’t it ?). Forums will remain useful for communities and won’t be replaced by wikis or blog. Though it’s true web applications tend to go toward simplifying : in an over-informed world, signal vs noise demands more simplicity. Vanilla’s succes is a nice example of this trend...

This being said, if you are interrested in web 2.0 + wikis => check StikiPad out

Agree to some of the concept that Adam brought up. Even though I have to point out that the ego of some open source community sometimes is way too much that they are always trying to do everything with their product. I’m not saying that this is wrong, because the more we want more features, the more the program will be more powerful.

So in this part, if the forum system trying to do the whole doc with their system, that will be the ego, but if MODx want to the doc on their own system, that will be a showcase of how powerful the system can be, because we’re a CMS system. That is also another rason why we still use SMF as the forum.

So in Adam’s reasoning, I will have to agree that we need to do it in MODx. If we can’t prove ourself to be able to do the content management for our documentation by ourself, then we are not worth enough to introduce this technology to other people, don’t you guys agree with me?

As far as the commenting goes, I 100% agree to this. Please do so, I find this commenting system on php.net really2 useful. It provides feedback to improve the doc specifically, as well as categorising the topic in a more specific manner, becase the related discussion or comment is displayed below the doc.

To response on Mark reasoning, we can provide another solution to have the document in print view which can exclude the comment, or having an option to hide all the comment while browsing the doc. We can also approach this, by having an auto system that will generate pdf on daily basis, which was discussed earlier in other topic.

Regards,

Here’s my take on it....

I think having an offical MODx Wiki is a good idea. In fact, I’ve been thinking about this myself. Why not just create a subdomain like wiki.modxcms.com and install an application like MediaWiki (www.mediawiki.org)? Like you said, Wendy, it wouldn’t replace the offical documentation, but it would certainly allow an easier route to keeping the documentation more up-to-date. With something like this in place, we could rework the offical documentation to resemble a more thorough documentation model with different sections and "chapters" in a more organized and linear fashion. Let the wiki be more non-linear and the offical documentation more linear with PDF versions to boot! If this is an idea everyone goes for, I’ll work with Ryan to set something like this up.

Sounds good Jeff!

Quote from: aNoble at Jan 28, 2006, 11:00 PM

My personal take on this is that a wiki would be great for documentation but I don’t think it should replace the official documentaiton. I like having "offical documentation" that you know is reliable and hasn’t been edited by someone who doesn’t know what they’re doing.

In fact I totally agree with this. The commenting system employed by PHP.net is so useful.

Quote from: davidm at Jan 28, 2006, 11:33 PM

I also agree comments on the documentation would be nice, but more in the way some wikis have with "Discussion page". I think it’s better not to clutter the documentation pages themselves.

I pesronally think Wendy has the right idea here. I agree with you David that the documentation could get a little hairy if there are tons of comments on each entry, but then I also agree with Wendy:

Quote from: Djamoer at Jan 29, 2006, 05:33 AM

To response on Mark reasoning, we can provide another solution to have the document in print view which can exclude the comment, or having an option to hide all the comment while browsing the doc. We can also approach this, by having an auto system that will generate pdf on daily basis, which was discussed earlier in other topic.

I think this would be the optimal way of organising the documentation. I have found the current documentation very useful, but I think it needs to be just right to encourage MODx to be more widespread.

Quote from: Bravado at Jan 29, 2006, 05:50 AM

Let the wiki be more non-linear and the offical documentation more linear with PDF versions to boot!

I think Jeff has also hit the nail on the head here too. MODx seems to be growing fast. Just look at the wonderful new features that were brought to us in a single minor version upgrade from 0.9.0 to 0.9.1!! To keep up with all these new features, the best way to document that is to let us users contribute towards a collaborative document.

Long live the official documentation, it’s proved to be highly useful and greatly structured. I feel as a MODx community member, I can contribute in other ways.


Quote from: davidm at Jan 28, 2006, 11:33 PM

About the web 2.0 angle, blog and wikis are "trendy", as is AJAX but different tools have different use (it’s deep, isn’t it ?).

About David’s point, I think Web 2.0 is referred more to as an attitude rather than a technology. It seems Web 2.0 is difficult to define. People don’t exactly know what Web 2.0 is, but they recognise it when they see it. It’s certainly strange.

Anyway, in conclusion, I don’t know what to conclude. Add removable comments on to the Official Documentation and create an official MODx Wiki to compliment the official documentation?

I think a wiki can prove useful for the writing process of the documentation, and the doc itself could as Jeff says be more linear.

The way we could go about this is use the wiki to write drafts and then once it’s okayed add it online to the documentation.

Yeah, just the way WikiMedia works along with the commenting system, this would definitely allow us to keep the documentation more up-to-date. This kind of functionality is something that I think might prove to be a little difficult to fully implement with MODx. Granted, it can definitely be done...but it’s just so much easier to take a popular wiki app and stick it into a subdomain rather than labouring away on wiki-like functionality with MODx. So, for now, to speed things along, I think a dedicated wiki app is the right choice. Then, later on, perhaps we can revisit the wiki and see about officially integrating it into the main site.

I’ve been looking a little bit on ways to output the content of pages to PDF. This might help alot with the official documentation.

Just my $0.02 -- I am 100% opposed to a Wiki for documentation. Though it has worked in some projects (I do like the WordPress codex when it is not down or so overloaded I can’t to a page for 20 or 30 seconds), we have a unique opportunity to develop an alternative solution that could bring in Wiki lovers and haters alike. It’s all just content; and the final content is the key, regardless of what kind of front-end WYSIWYG or Wiki/Textile-like editor we throw up for people to use to enter it.

I truly think in the time it would take someone to setup and maintain a MediaWiki installation, participate in this separate content community, and then move appropriate documentation back to the main documentation system -- despite being a drain of important resources to the project and a distraction for the real potential of MODx to be used to blur the lines of wikis, blogs, and content management systems -- we could easily implement ways to make our documentation system easier to participate in.

I honestly would rarely visit this wiki, and segmentation of our content in this way, would be detrimental to the project in my view, adding another point of user and content aggregation to worry about.

But again, this is just my opinion, and can be easily changed by compelling arguments to the contrary.