User Guide version 1 available for comment

7,075 Posts

davidm Reply #11, 18 years, 5 months ago

First : Thanks ricardosanX ! I’ll most definitely read it and if I find the time, might translate it in french.

About the wiki discussion, this is funny you should mention this. We have similar discussion at textpattern’s forum about the wiki, TextBook. I take care of the french doc here, and both english and french docs are not moving forward as they should while the community is very active and IMHO, talented. I am mentionning all this because when I came here, I had the sense that this community shared many common point with textpattern’s.

Anyway, my take on this is that wikis are powerful tools and one of the things I like that most CMS don’t have is revisionning. Also, a wiki like MediaWiki handles multilingual content very well. Not to mention TOC auto-generation which is nice. As Jason said, the WordPress Codex is one good example of sucessful wiki documentation (and about structuring the doc : see how it is user-oriented).

Yet, from a community point of view the efficiency of wikis depend of its adoption by those who will write for it. It’s key to set up a tool that will make writers want to contribute. In the end, features is not what will make a documentation project a success. People are.

With that in mind, you can make a choice. I like the idea of buiding something around MODx and I agree with Jason about the editor : more often than not that’s what you use to write and if it doesn’t fit for you, you probably won’t write. About Textile, I have been using it ever since I adopted Textpattern : it’s a cool syntax you’ll learn quite fast, less cluttered than the wiki syntax. But some people won’t click with it : some prefer Markdown. Some prefer WYSIWYG. It would be great to be able to choose.

Just for reference, Instiki is a simple yet efficient wiki featuring Textile, but it’s Ruby On Rails and I don’t know if a MODx integration would be doable...

.: COO - Commerce Guys - Community Driven Innovation :.

MODx est l'outil id

222 Posts

gadamiak Reply #12, 18 years, 5 months ago

David has pointed out probably the most important feature that comes with wiki -- an easy way to involve an active community to produce and maintain documentation. Wiki can help in speeding up the process by allowing anyone to provide content and securing it with revisioning. Actually, that’s what it was made for - to allow anyone to produce content quickly and without any computer skills.

Wikis most often use wiki markup, which is text based. There are a few reasons for this but the main are to assure a well formed content (semantic markup) and wide accessibility not dependent on platform and user agent. This can’t be always achieved with visual editors which frequently screw up the markup and don’t work on every UA. However the wiki markup is cluttered. There’s where Textile and Markdown come with help.

Regardless the editor, the well structured content may be presented in any imaginable way -- thanks to its good semantics it may be easily converted to other formats (PDF, RTF, XML...) and presented in a very slick way. The lack of good semantics is a problem, not its presence.

As David already mentioned, the choice of the editor may impact the productivity. So it’s important to have choice. But one must ensure compatibility with different UAs.

I am for a wiki. In my opinion it’s the best way to make documentation (I use one myself for my projects). Wikis offer comments, discussion and file attachments too. Anyway, BB way is not as effective in this role.

This is the web: the only thing you know about who will come is that you don't know who will come.

205 Posts

edge Reply #13, 18 years, 5 months ago

Hi

Well I am a newbie and I will happily read this through and use it as assistance in creating and understanding my first Modx site and let you have my thoughts. (e.g as a newbie, where I found I needed more info etc)

For what it’s worth I agree with a Wiki but I also like to have a manual I can print. Manuals give you the flexibility to read at your own pace no matter where you are located or if you are travelling. Soemtimes when I have been on the computer all day my eyes get tired and I switch off and pick up one of my refence books to read. But I always find I prefer areas like detailed explainations and examples of a particilar function better suited to being viewed online, probably because its when you are doing something more complex that at that point you need the most detailed and latest info available.

Only a suggestion, but if someone had the skills and it was possible to put together a full user manual (Book) I for one would be happy to pay something for it and also happy to download this.

Overall I think some visitors will prefer on-line documentation such as the Wiki, a tag reference manual, printed book or a combination and ideally having a choice will help meet each individuals needs.

Will give you my feedback early next week.

205 Posts

edge Reply #14, 18 years, 5 months ago

Hi Ricard,

Well I just downloaded the PDF, all I get is 20 blank pages ?

1,131 Posts

Bravado Reply #15, 18 years, 5 months ago

I’ll be doing a little research on wiki’s myself. The main thing I’m after is something that can plug into MODx relatively easy with some user permissions. Not only that, it needs to be easy to use, allow for a variety of ways of editing, and a way to compile a whole wiki into a multipage document. I would REALLY love to see something that can output an entire PDF...that would be sweet! Can’t have everything, I know...but some of the highlights would be nice. laugh

Guess we’ll see! Let’s start posting some wiki application ideas and narrow down our choices. Remember though...part of the choice will be based on how it will integrate with MODx. It could be the absolutely best wiki in the world...but would be useless if it doesn’t integrate or is a bitch to integrate with MODx.

Just some thoughts to think about.

Jeff Whitfield

"I like my coffee hot and strong, like I like my women, hot and strong... with a spoon in them."

6 Posts

clo75 Reply #16, 18 years, 5 months ago

Quote from: edge at Nov 25, 2005, 02:25 PM

Hi Ricard,

Well I just downloaded the PDF, all I get is 20 blank pages ?

same for me :’(

7,075 Posts

davidm Reply #17, 18 years, 5 months ago

Yeah for me too...

.: COO - Commerce Guys - Community Driven Innovation :.

MODx est l'outil id

MODX Staff
12,272 Posts

Ryan Thrash Reply #18, 18 years, 5 months ago

The User Guid has all been converted into the online documentation... Zi, can you delete/update the thread to clear up the confusion, please? Thanks!

Ryan Thrash, MODX Co-Founder
Follow me on Twitter at @rthrash or catch my occasional unofficial thoughts at thrash.me