Page d'accueil documentation Gladys


#1

Hello à tous!

Je viens de tomber sur ça sur Twitter, Ghost a sorti sa nouvelle documentation, et ça claque!

Actuellement on a pas de “homepage” de documentation qui relie les différentes documentation de Gladys, ça serait top qu’on ait une page d’accueil de la documentation un peu propre comme ça.

J’ai créé une carte sur le Trello =>


#2

Outch c’est méga propre :hushed:

Peut-être il serais plus logique de l’intégrer sur la plateforme dev ? Après tout c’est les dev qui en auront le plus besoin :smile:


#3

La documentation pourrait aussi concerner l’installation de Gladys et du coup ça intéressera les utilisateurs.
Il est parfois un peu dur de trouver le bon tuto (enfin ça s’est un avis personnel :slight_smile: )


#4

Je pense que ce sera un autre projet, la plateforme dev qu’on a actuellement est vraiment juste un front-end pour publier des modules. C’est un front-end ou il faut être connecté, donc pas disponible des moteurs de recherches et au contenu pas statique.

Ce que je verrais:

=> Juste retravailler sur le site actuel une page de documentation. Le site actuelle est statique, open-source et généré à partir de markdown donc il y a rien de mieux pour écrire de la doc.

=> Le + c’est que c’est statique, donc indexé, donc disponible sur google quand on fait une recherche, et donc plus facilement accessible pour les nouveaux.

=> Le encore plus gros + c’est que si on met ça sous le domaine gladysproject.com est pas un sous domaine c’est encore mieux pour le SEO :smiley:

La next step

Il faudrait identifier toutes les catégories qu’on recherche dans cette doc:

  • Concept
    • Architecture
    • Data model
  • Installation
    • Image Raspbian
    • Manuellement
  • Configuration
    • etc…
  • Development
    • Créer un module local Gladys
    • Créer un module distant Gladys
    • Coder dans un script
  • API
    • REST
    • Node.js
    • MQTT

Ce n’est qu’une liste non-exhaustive écrite sur le vif comme ça, si vous avez d’autres idées je suis preneur!

Ensuite une fois cette liste établie, on pourrait écrire la liste des articles dans chaque catégorie, faire un premier jet de design (ou trouver un template online), et ensuite gogogogo


#5

Du coup j’ai pensé à rajouter quelques trucs dans la liste :smile:

  • Concept
    • Architecture
    • Data model
  • Installation
    • Image Raspbian
    • Manuellement
    • Installation docker
  • Configuration
    • Logement
    • Pièces
    • Machines
    • Localisation
    • Android App
    • Gladys voice
    • Gladys bluetooth
  • Documentation (grand public)
    • Alarmes
      • Principe/Utilité
      • Créer/modifier/supprimer une alarme
    • Evènements
      • Principe/Utilité
      • Déclencher un événement (timeline/box)
    • Type d’événements
      • Principe/Utilité
      • Créer/modifier/supprimer un type d’événement
    • Scénario
      • Principe/Utilité
      • Créer/modifier/supprimer un scénario
    • Device
      • Principe/Utilité
      • Créer/modifier/supprimer un device
    • DeviceType
      • Principe/Utilité
      • Créer/modifier/supprimer un deviceType
      • Les différents type de deviceType possible et leurs différences
    • Zone
      • Principe/Utilité
      • Créer/modifier/supprimer une zone
    • Module
      • Principe/Utilité
      • Qu’est-ce qu’un module interne ?
        • Installation
        • Configuration
      • Qu’est-ce qu’un module externe ?
        • Installation
        • Configuration
  • Development
    • Créer un module local Gladys
    • Créer un module distant Gladys
    • Coder dans un script
  • API
    • REST
    • Node.js
    • MQTT
  • Tools
    • Gladys POD
      • Rôle
      • Installation
      • Configuration
    • Gladys MQTT Adapteur
      • Usage
      • Installation
      • Configuration
      • API

Voila c’est un peu près tout ce qui me vient à l’esprit pour le moment :thinking:
Et quand on aura ça ça sera déjà pas mal :stuck_out_tongue:
Mais avec une doc aussi fourni tu t’assure que tout les type d’utilisateurs y trouvent leurs compte qu’ils soient dev ou non ! Et au passage il faudrait lui donner bien plus de visibilité car actuellement la doc n’est présente que sur le site public mais elle devraient aussi être présente sur le forum ce qui éviterais beaucoup de post…

D’autant plus qu’actuellement la doc est accessible via l’onglet “Installation” sur le site, ce qui n’est pas super logique ^^


#6

Beau boulot, enfin, pas encore fait, mais belle analyse :slight_smile:


#7

Génial! Top ta liste Mathieu :slight_smile:

Pour le template que tu m’as envoyé en MP, c’est vraiment pas mal!

( pour archive => http://thetheme.io/thedocs/docs/code.html )

Si on part sur ça t’embête pas je vais l’acheter.


#8

@MathieuA Je repost ici le message que tu as mis et les investigations que tu as fais sur le thème :slight_smile: Tkt même si on l’a pas acheté pour l’instant tant qu’on l’utilise pas on a le droit de faire des tests.

Je préfère discuter ici honnêtement j’ai trop de MP je ne m’y retrouve pas sinon.

Voilà donc les screenshots =>

Personnellement je trouve ça top! C’est propre, complet, ça peut vraiment rendre bien.

J’ai juste encore une petite interrogations, ici la documentation est un site à part entière. J’aurais aimé intégrer ça au site Gladys, mais j’ai du mal à voir comment on pourrait faire ça sans que ça soit lourd en terme de navigation…

Tu aurais une idée ?

Parce que là tu as mis une navbar entière pour la doc, en même temps ça peut faire sens mais comment intégrer ça au site ?

Est-ce qu’on pourrait gérer ça avec une sidebar à la place ? et donc rester sur le site principal? :slight_smile:


#9

Pas de soucis @pierre-gilles ! J’ai préféré le mettre en MP dans un premier temps du fait de la nature payante du thème, mais si tu juge qu’on peux en discuter ici ça me va aussi ^^

Honnêtement je ne sais pas comment…
Déjà ton site est statique et utilise Bootstrap, je suis pas très familier avec ce genre de sites et en survolant le repo j’ai l’impression que les assets sont importé de façon automatique et pas directement en dur dans l’HTML (je me trompe peut-être) du coup Bootstrap et le thème de la doc (qui n’a pas besoin de Bootstrap) risque de rentrer en collision et faire des trucs bizarre :sweat_smile:

Ah moins de revoir complètement le site je ne vois pas comment faire… J’ai fais le choix de mettre une navbar justement pour pouvoir utiliser la sidebar pour les sous-catégories !
Après évidement on peu jouer sur des items multilevel dans la sidebar pour garder cet aspect catégories/sous-catégories mais comme tu l’a dit ça risque de devenir très lourd niveau navigation :confused:

Ce que je pensais moi c’était de créer un site à part entière qui serais accessible depuis un onglet “documentation” du site principal :slight_smile:
Mais après effectivement ça fait toujours deux sites différents et donc deux domaine à payer aussi :stuck_out_tongue:

Sinon comme j’te disais juste au dessus il faudrait revoir tout le site principal mais bon…


#10

Ouai c’est pas évident le cas jekyll + documentation.

@MathieuA en général les sous domaine c’est gratos.

@pierre-gilles tu ne veux plus de sous domaine right ?


#11

Je poste peut être dans le vent, mais peut être que ça peut vous intéressez ==> https://www.bookstackapp.com/

Je l’ai depuis un ptit moment, sur un hébergement mutuel et ça répond franchement bien ^^

Vous n’avez qu’à adapter la partie utilisateur si vous voulez une gestion.


#12

Sympa ! (Même si je commence à saturer de voir du bootstrap partout… :p)


#13

Tkt la partie Jekyll ça change rien :slight_smile: on peut faire plein de pages différentes, c’est hyper simple! Je t’expliquerais.

J’ai bien compris que tu voulais mettre ça sur un subdomain :stuck_out_tongue:

C’est pas une question de coût (c’est gratuit un subdomain), c’est juste que:

  • C’est peut-être plus clair d’avoir tout sur le site principal. Actuellement c’est le bordel, on a le site developer, le site principal, j’aimerais unifier et avoir tout sur le site principal. Comme ça un nouveau utilisateur il arrive, en quelques minutes à naviguer sur le site il comprend comment installer Gladys, quels sont les modules existant, fin c’est plus clair.
  • Niveau SEO je trouvais ça intéressant de garder tout ce contenu sur le domaine principal. Certes c’est plus chiant à développer mais je pense que ça a clairement un vrai intérêt en terme de SEO

Ya pas à revoir tout le site principal, ça pourrait être juste l’onglet “installation” qui devient un onglet “documentation”, tu pense pas ?

A débattre!


#14

C’était mon idée de départ mais je veux rien du tout c’est toi le chef c’est toi qui décide :rofl:

Bah au contraire moi je trouvais ça plus cohérent de bien séparer :thinking:
Après si tu me laisse remplacer la navBar du site quand l’user va dans l’onglet documentation moi je veux bien :stuck_out_tongue:
Parce que s’en la navBar ça va être difficile de faire une navigation propre et légère…


#15

Je suis d’accord! J’avoue que j’ai pas de meilleurs idées pour gérer la navigation donc va pour un subdomain! Sold!

Tu veux que j’achète le thème du coup ?


#16

Oh bah cela s’annonce bien pour la documentation !

Lorsque vous lancerez tout ça, je serais contributeur sans soucis pour faire des petites documentatons ! :slight_smile:


#17

Coooool :slight_smile:

Comme tu veux ! Mais je pense qu’on trouvera difficilement mieux…

Merci @Totof on aura besoin d’aide ^^


#18

C’est fait! J’ai acheté le thème je t’ai envoyé le zip sur Slack


#19

Hello tout le monde !

Du coup comme @pierre-gilles a validé le thème et la liste, je me suis lancé sur la mise en place du site !
Après quelques recherches et quelques tests j’ai fini par adopter Jekyll pour plusieurs raison !

Facilité de mise en place, de maintenance et surtout tout le site est auto généré grâce aux fichiers markdown !
Donc toute la doc sera écrite en markdown afin de faciliter les contributions et surtout le site suivra l’évolution des fichiers avec beaucoup de souplesse ( je suis fier de moi, je l’avoue je sur vend la chose)

Bref le site est dispo sur mon Github pour le moment et viendra certainement rejoindre l’organisation Gladys si @pierre-gilles l’accepte :smile:

J’ai écrit un joli readme et un joli contributing pour vous guider dans vos contributions !

L’adresse de mon Git =>

L’adresse du site (à savoir qu’il est vide pour le moment) =>

https://mathieuandrade.github.io/documentation.gladysproject.com.jekyll

J’espère voir fleurir les contributions :slight_smile:
Merci d’avance pour vos retours !

Le site est disponible en Anglais ET en Français


#20

J’comprend pas c aigri “En cours…” par tou. le site bog !

Bien joué @MathieuA !!