<![CDATA[ User Guide version 1 available for comment - My Forums]]> https://forums.modx.com/thread/?thread=25228 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129431 ]]> rethrash Nov 25, 2005, 10:06 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129431 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129430 davidm Nov 25, 2005, 10:00 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129430 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129429 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 :’(]]> clo75 Nov 25, 2005, 08:52 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129429 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129428 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. smiley Just some thoughts to think about.

]]> Bravado Nov 25, 2005, 08:26 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129428 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129427
Well I just downloaded the PDF, all I get is 20 blank pages ?]]> edge Nov 25, 2005, 08:25 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129427 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129426
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.]]> edge Nov 25, 2005, 08:19 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129426 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129425
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.
]]> gadamiak Nov 25, 2005, 07:37 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129425 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129424 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...



]]> davidm Nov 19, 2005, 03:29 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment?page=2#dis-post-129424 <![CDATA[Re: User Guide version 1 available for comment]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment#dis-post-129423
I like the idea of having a graphical documentation for modX. One thing that find it hard to use wiki, there is no end to it, and every new people who need to read the documentation will give up, even before trying to understand the modX system itself.

I know this is an old forum post, but from what I can see now, so far the docs is awesome, I can get use to the whole modX idea in a few hours. Two thumbs up for the gull graphical explanation in each documentation pages. Keep up the good work guys.

I’m looking forwad for the next release of TP4, which is going to have a full documentation of the API itself. I’m currently have a stack load of project that I’m planning to implement them in modX.

Hope my post can encourage the core members for this script. Glad to have this wonderfull community and developers.

Regards,
Wendy Novianto]]> wendy Nov 18, 2005, 09:50 PM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment#dis-post-129423 <![CDATA[Re: Something a bit visually more exciting]]> https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment#dis-post-129422 * The are very text based - I'd prefer something that would be easier to format and spice up which leads me to...
* Visual design - I want the User Manuals to be "slick". These are tools I want professional client to see and say "Ah, just like a professional manual"

Maybe we need to distinguish between the collaborative tools we use for knowledge sharing (like Wiki) and the Manuals for End Users.
Absolutely. And with the simplicity and flexibility I envision as the future of this CMS / framework, End User Manuals might be best left to those that want to offer value-added commercial development and support services. Charge for your slick end-user documentation. This is what free-software based business models are all about.


Ideally the Online Manual would:
a. have full range of formatting tools like HTMLarea
b. be easily exportable to other formats
c. allow for creative graphical elements eg. Callouts, Ideas, Reminders etc
d. have a user friendly navigation system that new users understand (eg DHTML tree menu)

Some Manuals from Commercial CMS and software>>
http://manual.soholaunch.com/
http://www.miro.com.au/Docs/MamboCMS/index.html (commercial Mambo manual)

Do you know of documentation tools (including wikis) with this kind of functionality?
Not yet, but that is exactly why I am asking. At a minimum, I'd like to have this be a MODx based system, that does indeed allow different input/formatting tools, be it a WYSIWYG, wiki style, and/or potentially something like Textile (see http://textism.com/tools/textile/ and http://www.textpattern.com/), which just looks like an alternate Wiki-style input syntax.

Thanks for the input so far guys; this will help shape the development of core and extended documentation and product features.]]> opengeek Apr 04, 2005, 10:52 AM https://forums.modx.com/thread/25228/user-guide-version-1-available-for-comment#dis-post-129422