Organization of tutorials, docs, etc.

[AlexisDrogoul]

Looking at the site, I see less and less reasons to separate so clearly "Tutorials" and "Documentation" (esp. since part of the documentation can be browsed like a tutorial).

An organization (at least of the menu) with:

1) Learn

• Get started
• Step by Step
• Tutorials
• User Guide
  • Using the platform
  • Models library
• Modeler Guide
  • GAML
  • Recipes
  • Plugins

2) Share (ex-Community) ... and its sub-menus...

3) Download

Would be much more appealing in my opinion, grouping together all the "learning" options

[mazarsju]

Yes, this was an old debate... The separation between "Tutorials" and "Documentation" is not very clear, I agree. But then, we need to gather some of the 8 parts to reduce the number of parts under "Learn". For me, the part "Get started" can be reachable just from the home page (A long debate already done against Nicolas ^^'). Tutorials can be regrouped under an other part, such as "Recipes".

This would lead to this following organisation :

• User Guide
• Learn GAML Step by Step
• Modeler Guide
• Recipes and Tutorials (including plugins and tutorials)

[mazarsju]

I forgot "Model library" in the list... Maybe we should put it in last position ?

There is the question of the "Features" parts... ( cf #40 ) It is not an "action" as "learn", "share", "download", so what name should we give ?

What is your opinion about all this @sriramab ?

[sriramab]

Hmm, well I think Alexis already aptly used the word Discover for Features. Though not sure it will be clear to the user if we use Discover.

I think there is clear distinction for Tutorial and Documentation and in my opinion warrant segregation. Tutorial is when someone is holding your hand ( tutoring that is) and teaching/ leading you to build a model by explaining the basic building blocks. Documentation on the other hand is like a dictionary, a user is on his own - no guiding hand, looking for whatever he wants. I would rather combine Tutorials and User Guide, as in a user guide, there is still a guiding hand introducing you to the interface. And when you combine, it could be a good idea to have table of contents of the whole tutorial (pdf) clearly visible on the download page, So that user knows what is in the tutorial ( in this case, guide to interface and tutorials to learn model building)

May be a lot of work, but tutorials should keep referring to the various interface elements introduced in user manual.

so the tutorial contents could stand like this:

1. Downloading and installing
2. Learning the interface
3. Advanced preferences/ mentions also about other resources - google group, github , facebook, youtube etc.
4. Basic Model - Predator Prey (just an example, could be something else)
5. and then incremental models with increasing complexity.

I do not think step-by-step is necessary, as tutorials are step-by-step, unless your reference to step-by-step is to the learning paths.

regards, Srirama

[sriramab]

May be Explore instead of Discover?

[mazarsju]

Gathering or not References and Tutorials... Seems like everyone is not agree on that. I just talked to @dphilippon, he is also strongly against gathering References and Tutorials.

@sriramab :

• The first steps you mention are in fact what is called the current "get started". I agree few things have to be changed (changing the images, putting the names under the different buttons...) but we have here all the informations we need to install, have a first contact with the platform, and knowing what to do to be part of the community. The "User manuel" is more a "reference" than a "tutorial" for me... What do you think ?
• Regarding your comment about the "step-by-step" part, I think it is a very useful part for newcomers in order to understand the philosophy of GAML. And the goal of this "step by step" part is not exactly the same as using "learning path" : the user who uses the "step by step" part is a new user who does not know really what is important to learn, although the user who uses the "learning path" is a new user who knows what he wants to do with the platform, but he does not know how to learn it.

[mazarsju]

Here is a proposal for the "get started" page :

• it will be open by default with the page "get gama".
• the images are a little more explicites
• the name of each part is displayed under each circle

[mazarsju]

Moved to https://github.com/gama-platform/gama.doc/issues/17