On Mar 1, 2010, at 11:08 AM, Thomas Mortagne wrote:

On Mon, Mar 1, 2010 at 10:58, Silvia Rusu <[email protected]> wrote:

...

Hello,

I would like to propose we update the User Guide documentation so that it's more helpful to users that start using XWiki, whether they are programmers or not. The purpose of the guide is to get users up to speed with the XWiki basics, to gather these resources in one place.

You can find my proposal for the user guide here: http://dev.xwiki.org/xwiki/bin/view/Drafts/UserGuide

Please feel free to make suggestions for other pages to be included or changes you think should be made. Remember this is not a TOC for all the documentation, but rather a selection of links to help you get started with XWiki.

It should maybe be renamed as "Get Started with XWiki" instead of "User Guide" then.

Actually it's meant to be a full User Guide to replace the current page at http://enterprise.xwiki.org/xwiki/bin/view/UserGuide/ (the existing Getting Started guide would disappear). Basically the idea is to have a single user guide that starts with some basic feature explanations (the getting started part) and that increases in complexity as you progress through the guide. Thanks -Vincent

...

Thanks, Silvia

----- Silvia Rusu

Hi Vincent, Thanks for the feedback On 3/1/2010 12:17 PM, vmassol [via XWiki] wrote:

Hi Silvia,

On Mar 1, 2010, at 10:58 AM, Silvia Rusu wrote:

...

Hello,

I would like to propose we update the User Guide documentation so that

it's

...

more helpful to users that start using XWiki, whether they are programmers or not. The purpose of the guide is to get users up to speed with the XWiki basics, to gather these resources in one place.

You can find my proposal for the user guide here: http://dev.xwiki.org/xwiki/bin/view/Drafts/UserGuide

Please feel free to make suggestions for other pages to be included or changes you think should be made. Remember this is not a TOC for all the documentation, but rather a selection of links to help you get started with XWiki.

Good start! It's cool that you're working on this, we absolutely need it :)

Some feedback:

* It doesn't feel like a guide right now. It seems to be a collection of links to other places. Personally I like that because it avoids duplication. However I wonder what will first time users think. It probably makes it hard for them to read. Also the current getting started guide from Guillaume (which would disappear as a consequence) has a lot more texts and explanations that need to be reintegrated in the user guide.

I think the collection of links makes it easier for users to spot the documentation they are interested in. I agree that Guillaume's Getting Started guide needs to be reintegrated in the user guide as much as possible. As a consequence I've added links to part of the pages. Other issues however, like managing user groups, are better described in the platform documentation (more information, screenshots), so I preferred adding a link to those resources instead. If the Getting Started pages will be removed altogether I can copy their content to different pages and set the User Guide as their parent. I'll also include more screenshots.

* It's missing an overall TOC

I added the TOC at the "XWiki Basics" level, but this can easily be changed.

* I only see "XWiki Basics" but this guide is supposed to be a full guide to all features. Is it simply because it's not finished? How would you organize the rest?

My initial idea was for the guide to provide links to part of the documentation. This would be the pages that are most necessary when starting with XWiki and that don't require programming or advanced admin skills to understand. (Hence "This is not a TOC for all the documentation, but rather a selection of links to help you get started with XWiki." in the first email). I've extended the invitation for users to visit the Developer & Administrator's Guides to further their skills and get a deeper understanding of XWiki. This way "Getting started" is interpreted not necessarily as the first steps to take with XWiki, but rather as mastering the basics of working with XWiki, with the possibility of enhancing your skills as you read the rest of the documentation. Should we add links to all our existing resources I think the User Guide may get too crowded and users with no significant coding experience may have trouble understanding it. WDYT?

* I think you need the guide to start with a single page that is a TOC and have more separate pages. This will come naturally as a consequence of adding more explanations/texts to the each section (see first point above). The idea behind the User Guide page was that of a TOC (this is why it looks more like a collection of links). The small pieces of text are there to put the links in context, so that they make sense when seeing them for the first time.

I agree with the having more separate pages. While in some sections the existing documentation is enough, for other areas we could add a lot more details to make things clear. This is the case of the blog for example (which is not yet included) for which there will be a separate guide. After the blog guide is ready there will be of course a link to it from the User Guide. The same goes for the WYSIWYG editor. This can be also done for other sections if users consider the existing documentation is not clear/descriptive enough.

* The guide needs a lot more screenshots IMO. There should be screenshots everywhere. Remember that an image is worth a thousand words ;)

I think we should avoid having images on the User Guide's main page (the one in Drafts) since this page's role is that of a TOC. I agree with having many screenshots in the sub-guides (e.g. the blog and wysiwyg guides, the new pages resulting from the old "Getting Started" guide)

Thanks -Vincent

...

Thanks, Silvia

_______________________________________________ users mailing list [hidden email] http://lists.xwiki.org/mailman/listinfo/users

View message @ http://n2.nabble.com/Proposal-Improving-the-User-Guide-documentation-tp46533... To unsubscribe from [Proposal] Improving the User Guide documentation, click here.

This is obviously a work in progress, as it entails creating many child pages and changing the current main draft, however feedback early on in the process is appreciated so the final result answers most of our first time user's basic questions. Thanks ----- Silvia Rusu Tester & Documentation Writer - XWiki http://twitter.com/silviarusu -- View this message in context: http://n2.nabble.com/Proposal-Improving-the-User-Guide-documentation-tp46533... Sent from the XWiki- Users mailing list archive at Nabble.com.

Hi, After reading all your emails I think the best solution is having both a guide for first time users and a complete guide to all XWiki features: - The Getting Started page can become the draft included in this email - The User Guide could be a TOC of all existing resources as Vincent suggested. This way both experienced and unexperienced users are happy: - First time users can discover XWiki one step at a time with the help of the "Getting Started" page - Experienced users don't have to look for information through the different wikis and can instead go to the User Guide TOC. Smaller guides will be made as suggested in the previous email for the blog, wysiwyg, etc. These will be linked from both the Getting Started page and the User Guide. WDYT? ----- Silvia Rusu Tester & Documentation Writer - XWiki http://twitter.com/silviarusu -- View this message in context: http://n2.nabble.com/Proposal-Improving-the-User-Guide-documentation-tp46533... Sent from the XWiki- Users mailing list archive at Nabble.com.

Please somedbody of the long term addicts should write a book about XWiki. All important projects do have books and for many people the availbility of printed literature marks the difference between some open source project and an important open source project. Before picking up a new software and spending much time with learning and practicing many people check amazon for the availability of literature. +1 for better Online documentation +10 for a decent book covering all levels from beginner to developer Andreas Caleb James DeLisle schrieb:

+1

I believe in making XWiki as friendly as possible to application developers so I think we should cater to people who are new to XWiki but have experience in development. As an example I found the FAQ Tutorial confusing and patronizing but I was at home with the object editor.

Anyway just an idea and big +1 for all kinds of documentation.

Caleb

Silvia Rusu wrote:

...

Hi,

After reading all your emails I think the best solution is having both a guide for first time users and a complete guide to all XWiki features:

- The Getting Started page can become the draft included in this email - The User Guide could be a TOC of all existing resources as Vincent suggested.

This way both experienced and unexperienced users are happy: - First time users can discover XWiki one step at a time with the help of the "Getting Started" page - Experienced users don't have to look for information through the different wikis and can instead go to the User Guide TOC.

Smaller guides will be made as suggested in the previous email for the blog, wysiwyg, etc. These will be linked from both the Getting Started page and the User Guide.

WDYT?

----- Silvia Rusu Tester & Documentation Writer - XWiki http://twitter.com/silviarusu

_______________________________________________ users mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/users