[iTowns-dev] Tutorials

[Pierre-Eric Pelloux-Prayer]

Hi,

> 
> Victor and I wrote a draft for tutorials (some of it is obsolete), in the readme here:
> https://github.com/iTowns/itowns2/tree/README

Good idea, and thanks for working on the documentation topic.


> 
> I think ideally we should have a tutorials page which list all tutorials which will have their own page.
> 
> Something like:
> itowns-project.org/tutorials.html
>   itowns-project.org/tutorials/basicstartup.html
>   itowns-project.org/tutorials/addGeometryTutorial.html
>   ...
> 

I really like the three.js/docs layout.
On the same page you get access to: tutorials/introduction articles, API documentation and examples.

One big + is that you can just type something in the search bar (eg: Material) and you get to discover
everything available on the subject.


> If you have other ideas on that topic don't hesitate!

Here are 3 independant ideas:

1. for examples/tutorials, I think litterate programming offers a nice solution.

A big part of https://github.com/iTowns/itowns2/blob/README/README.md is a copy paste of index.html.
I see at least 2 benefits to write the same content direclty in index.html:
  - index.html would become documented :)
  - the comments would be easier to keep synchronized with itowns changes (it's too easy to forget to
    update the README.md or addGeometry.md)

2. consistent documentation style for examples and API

See issue https://github.com/iTowns/itowns2/issues/314 (discussing jsdoc, docco and other tools for API doc)

Also it could make sense to use a single tool to build our website (instead of jekyll + API doc tool + examples/tutorial 
doc tool).
Here's what I imagined: docco for API/examples doc and a static landing page showing the README.md + screenshots of
itowns app (like https://threejs.org/).

3. I believe that, as iTowns' users will also be three.js users,  it makes sense to try to match the style and
organization of three.js website.
I guess that all the discussed tools have configurable layout/template, so it shouldn't be too hard to achieve.


Regards,
Pierre-Eric