[Jderobot] Refactorización del mediawiki

[JoseMaria]

Estupendo Borja!, 

sí, el manual es la mejor documentación que tenemos pero necesita una
buena refactorización para afinarlo y hacerlo más útil. Lo hemos ido
construyendo a base de empujones y un poco por eso hay partes
desactualizadas... Por mi parte avanti a todos los puntos que propones,
con los comentarios que pongo entre líneas. 

Especialmente para los nuevos: recordad que es un manual colaborativo,
si veis algo mal o que falta... corregidlo o ponedlo sin miedo. La
herramienta MediaWiki permite dar un paso atrás si os equivocais, no
pasa nada. Es la única manera de mantener actualizada la documentación
de un proyecto software tan grande como este.

> Lo primero de todo, en la página principal, cambiar de orden las
> dependencias y el proceso de instalación. Si lo que queremos es
> instalar jderobot, lo suyo es que primero nos instalemos las
> dependencias, ya que de otra forma no podremos instalar jderobot.
> 
Ok

> En la parte de dependencias, ponerlas todas ahí. No puede ser que si
> queremos instalar OpenCV, que es una dependencia que tienen muchos
> componentes de jderobot, tengamos que acceder a otra página del
> mediawiki. Lo mismo ocurre con ICE, por ejemplo, cuando aquí es
> todavía más evidente que es muy importante para el proyecto... Y lo
> peor de todo es que ICE está ahí medio escondido, que a poco que vayas
> rapidillo te lo saltas y se te olvida instalarlo.
> 
Ok, sí, buena idea poner todas las dependencias en un sitio único, en la
sección de instalación.

> En el hilo de lo anterior, no entiendo por qué si hay una parte que
> "Instalación de dependencias" se esté metiendo también "Desarrollar
> con esta dependencia". No hay más que mirar la parte de OpenCV de la
> que he hablado antes para comprobar esto. Lo suyo es que si son
> dependencias, son dependencias, y si queremos desarrollar con ellas ya
> nos preocuparemos después de mirarlo. Creo que aquí la división
> debería de ser no tanto por el paquete/biblioteca que se necesite y
> meter todo ahí, sino más bien por funcionalidad (si queremos
> instalarlo, si queremos desarrollar con ello, etc).
> 
Ok a separar "instalación de dependencias" de "desarrollar con esta
dependencia" (este último puede ir al FAQ o en el "Developing
applications with JdeRobot" --lo cuento al final del mensaje--). Hasta
ahora un criterio era poner en el manual lo propio y en el FAQ las cosas
externas en las que nos apoyamos (Gazebo, ICE, OpenCV...). Cambiemoslo
tal y como sugieres.
> 
> La dependencia con GearBox ya no existe, ¿verdad? Tampoco se hace nada
> con Player/Stage ya, solo con Gazebo (en cuanto a simuladores hablo,
> claro). Creo que esto se podría eliminar.

Yes

> Como ya he comentado en otro correo, se eliminará la tabla de
> dependencias. Todas las dependencias ya quedan lo suficientemente
> claras, bien en el apartado de dependencias como tal, bien cuando vas
> a compilar y te las dice el bueno de cmake :)

Quizá podríamos mantener una descripción más sencilla, como dice Fran.

> Por otra parte, existen dos secciones diferenciadas y que a priori
> alguien nuevo no sabría muy bien cómo identificar. Me refiero a
> drivers y tools. De acuerdo que tenemos componentes que son drivers y
> otros que son herramientas, pero alguien que se haya descargado de
> nuevas el repositorio lo único que verá, en todo caso, son
> componentes, interfaces y bibliotecas, pero nada de drivers y
> herramientas. Creo que esto se podría poner bajo un mismo paraguas
> (componentes) y luego explicar que hay diferentes tipos de
> componentes.
> 
Hasta ahora los distinguiamos por funcionalidad: los drivers
proporcionan acceso a sensores y actuadores, y las tools justo eso,
herramientas. Además hay herramientas que no son componentes (visualHFSM
por ejemplo). Pero igual merece la pena organizarlo como propones para
simplificar: componentes-interfaces-bibliotecas. Alex también apuntaba
hace tiempo a ponerlo así. Bien, agrupemoslo justo como propones,
indicando que unos son drivers, otros tools, y otros ni una cosa ni
otra :-).

> Además, también está el tema de que las explicaciones de cómo hacer
> funcionar los componentes está muy dispersa. En "Running JDERobot" hay
> un poco (desactualizada también, porque se habla de Player y
> playerServer) pero luego también nos podemos encontrar algunas
> explicaciones en drivers o en tools. Creo que en todo caso en esas
> secciones se tiene que explicar cómo funcionan y cómo lanzarlas, pero
> la explicación de cómo hacer correr cameraserver+cameraviewer o gazebo
> +plugin+introrob debería de ir en el Running JDERobot. En cambio, en
> esta sección de Running JDERobot no debería de ir la explicación de
> cómo crear un interfaz de ICE o cómo programar para OpenCV, eso
> debería de ir en otra sección dedicada a ello (como "Desarrolla con...
> OpenCV/ICE/PointCloud/etc").

Bien. Por un lado una sección "Running JDERobot" donde mostramos como
configurar tal o cual combinación, que se vean ejemplos de uso...
actualizando lo que tenemos y ampiandolo. Y por otro lado una sección
"Developing applications with JdeRobot" donde describimos desde la
óptica del programador ejemplos/consejos de programación con  opencv,
ice, pcl...

Qué buena pinta está tomando. Avanti,

JoseMaria
-- 
http://gsyc.urjc.es/jmplaza 
Universidad Rey Juan Carlos