diff --git a/contributordoc.md b/contributordoc.md index 31bc784e..9d6a6212 100644 --- a/contributordoc.md +++ b/contributordoc.md @@ -2,6 +2,9 @@ * [General ways of contributing to YunoHost](/contribute) * [Writing documentation](/write_documentation) + * [Documentation wrinting guide](doc_writing_guide) + * [markdown guide](/doc_markdown_guide) + * [Propulser son code avec Git & GitHub](/doc_use_git) * [Chat rooms](/chat_rooms) * Application packaging * [Apps wishlist](/apps_wishlist) diff --git a/contributordoc_fr.md b/contributordoc_fr.md index 9821b97c..afcc9e9b 100644 --- a/contributordoc_fr.md +++ b/contributordoc_fr.md @@ -2,9 +2,9 @@ * [Liste des façons de contribuer à YunoHost](/contribute) * [Écrire de la documentation](/write_documentation) - * [Guide de redaction de la documentation](dc_writing_guide_fr) - * [Guide markdown](/doc_markdown_guide_fr) - * [Propulser son code avec Git & GitHub](/doc_use_git_fr) + * [Guide de redaction de la documentation](doc_writing_guide) + * [Guide markdown](/doc_markdown_guide) + * [Propulser son code avec Git & GitHub](/doc_use_git) * [Salons de discussion](/chat_rooms) * Packaging d'application * [Liste d'applications souhaitées par la communauté](/apps_wishlist) diff --git a/doc_markdown_guide.md b/doc_markdown_guide.md index 7afe55b8..b42deefe 100644 --- a/doc_markdown_guide.md +++ b/doc_markdown_guide.md @@ -1,21 +1,8 @@ # Markdown Guide -**Index** - - [The different title levels](#TitleLevels) - - [Paragraph formatting](#ParagraphFormatting) - - [Link creation](#LinkCreation) - + [Anchor creation](#AnchorCreation) - - [Display images](#DisplayImages) - - [Citation formatting](#CitationFormatting - - [Lists](#Lists) - + [Ordered](#Ordered) - + [Unordered](#Unordered) - - [Tables](#Tables) - - [Code segments](#CodeSegments) - Markdown is a markup language from 2004, with many add-ons supporting its function and existence. This guide explores the possibilities and formatting of the language in the context of YunoHost documentation, and not the Markdown language on its own. -Markdown allows formatting of text using tags, in human-readable format; even with formatting. Outside of plaintext editors, a number of specific programs exist. (Markdown on [framalibre.org] (https://framalibre.org/recherche-par-crit-res?keys=markdown)). It is easy to deal with. +Markdown allows formatting of text using tags, in human-readable format; even with formatting. Outside of plaintext editors, a number of specific programs exist. (Markdown on [framalibre.org](https://framalibre.org/recherche-par-crit-res?keys=markdown)). It is easy to deal with. ## The different title levels diff --git a/doc_markdown_guide_fr.md b/doc_markdown_guide_fr.md index 1a8ac21d..dcc12fca 100644 --- a/doc_markdown_guide_fr.md +++ b/doc_markdown_guide_fr.md @@ -1,23 +1,10 @@ # Guide Markdown -**Index** - - [Les différents niveaux de titres](#NiveauxTitres) - - [Formatage dans les paragraphes](#FormatageParagraphe) - - [Créer des liens](#CreerLiens) - + [Créer des ancres](#LiensAncres) - - [Afficher des images](#AfficherImages) - - [Formater une citation](#FormaterCitation) - - [Les listes](#UtiliserListes) - + [Listes ordonnées](#ListesOrdonnees) - + [Listes non ordonnées](#ListesNonOrdonnees) - - [Les tableaux](#UtiliserTableaux) - - [Bloc de Codes](#BlockCodes) - -Le Markdown est un langage de balisage créé en 2004, de nombreux add-on développant les possibilités de ce langage existent. L'objectif de ce guide est de tendre vers l’exhaustivité des possibilités de ce langage de formatage dans le cadre de la documentation de YunoHost et non du langage Markdown en général. +Le Markdown est un langage de balisage créé en 2004, de nombreux add-on développant les possibilités de ce langage existent. L'objectif de ce guide est de tendre vers l’exhaustivité des possibilités de ce langage de formatage dans le cadre de la documentation de YunoHost et non des langages Markdown en général. Markdown permet de formater du texte à l'aide de balises, il permet une lecture *humaine* du texte ; même avec le formatage. Même si un unique bloc note est nécessaire il existe de nombreux logiciels markdowns (Markdown sur [framalibre.org](https://framalibre.org/recherche-par-crit-res?keys=markdown)). Sa prise en main est relativement facile. -## Les différents niveaux de titres +## Les différents niveaux de titres En rédigeant des titres comme suit : ```markdown @@ -37,7 +24,7 @@ Ils apparaissent comme cela : ##### Titre de niveau 5 ###### Titre de niveau 6 -## Formatage dans les paragraphes +## Formatage dans les paragraphes Pour taper un retour à la ligne sans créer de nouveau paragraphe, il est nécessaire de taper **deux espaces consécutifs**.Sans cela, le texte continuera à la suite en respectant les contraintes générales du style de la page. @@ -55,7 +42,7 @@ Pour du texte en *italique il faut encadrer par un astérisque `*` * Pour rédiger du **texte en gras par deux astérisques** On peut aussi ~~barrer le texte~~ en encadrant avec deux tildes `~` -## Créer des liens +## Créer des liens Pour créer un lien vers un site hors de la documentation de YunoHost : @@ -66,16 +53,17 @@ Pour créer un lien vers un site hors de la documentation de YunoHost : s'affichera comme tel : [Texte à afficher](https://lelien.tld) -C'est identique pour les pages de la documentation, excepté que le lien est interne. Il renvoie au fichier du wiki, sans extension de fichier (le `.md`) : +C'est identique pour les pages de la documentation, excepté que le lien est interne. Il renvoie au fichier du wiki, sans extension de langgue et de fichier (le `_fr.md`) : +```markdown +[Page du wiki](/write_documentation) ``` -[Page du wiki](write_documentation_fr) -``` -[Page du wiki](write_documentation) -### Créer des ancres +[Page du wiki](/write_documentation) + +### Créer des ancres Une ancre permet de faire un lien vers un point précis dans une page, c'est comme ça que fonctionnent les index en haut de page. Pour créer une ancre, il faut insérer du code à l'endroit de l'ancre sous la forme suivante : -``` +```markdown Du texte qui sera ne sait même pas qu'il a une ancre ``` @@ -84,33 +72,35 @@ Du texte qui sera ne sait même pas qu'il a une ancre Il ne reste plus qu'à désigner l'ancre au texte que l'on souhaite rendre interactif : -``` -[Mon titre qui renvoie](#NomDeLAncre) +```markdown +[Mon titre qui renvoie](#nom-du-titre) ``` -[Mon titre qui renvoie](#NomDeLAncre) +[Mon titre qui renvoie](#nom-du-titre) -## Afficher des images +## Afficher des images Pour afficher des images, le principe est identique aux liens, excepté l'ajout d'un `!` avant le texte à afficher qui est ici considéré comme le texte à afficher en cas d'impossibilité de chargement de l'image. Une description de l'image convient. -``` +```markdown ![Logo Yunohost](/images/logo.png) ``` ![Logo Yunohost](/images/logo.png) + Il est possible de faire un lien avec une image, exemple : +```markdown +[![Logo Yunohost](/images/logo.png)](/write_documentation) ``` -[![Logo Yunohost](/images/logo.png)](write_documentation) -``` -[![Logo Yunohost](/images/logo.png)](write_documentation) +[![Logo Yunohost](/images/logo.png)](/write_documentation) L'encart de *texte à afficher en cas d'impossibilité de chargement de l'image* n'est pas obligatoire mais fortement recommandé. -## Formater une citation +## Formater une citation Les citations permettent de mettre en valeur un propos tenu par une autre personne, le wiki gère lui même la façon dont c'est valorisé. Markdown utilise un chevron fermant, ce symbole : `>`, pour annoncer une citation. Il suffit de les rajouter avant la citation, comme tel : -``` + +```markdown >Du texte de citation du premier niveau >qui peut être formaté en différentes lignes @@ -125,15 +115,15 @@ S'affichera : >> Et une seconde citation >> avec des doubles chevrons -## Les listes +## Les listes Les listes permettent d'afficher une suite de textes dans une présentation facile, c'est ainsi que sont rédiger les index tels que celui de la page de la [documentation contributeur](contributordoc). -### Listes ordonnées +### Listes ordonnées Les listes ordonnées peuvent s'incrémenter autant que vous le désirez, il n'est pas obligé de donner la bonne correspondance au nombre. Il est possible de noter avec des `1.` comme des `7.` et installer trois espaces pour marquer l'incrémentation. Pour une meilleure compréhension du texte brut, il peut être bien d'utiliser les chiffres de manières croissantes pour marquer l'incrémentation, mais c'est bien les trois `espaces` conséquents avant la sous-liste qui désigneront l'incrémentation. -``` +```markdown 1. Liste 1 1. Liste 2 1. liste 3 @@ -167,11 +157,11 @@ On obtient : 3. Liste 5 4. liste 6 -### Listes non ordonnées +### Listes non ordonnées Pour créer une liste non ordonnée, il faut utiliser les symboles `*`, `+` ou `*`. Cela ne changera pas l'apparence du marqueur dans la restitution du texte. C'est l'incrémentation de la liste qui définira le visuel. Pour une meilleure lecture du texte brut, il peut être bien d'utiliser les différents symboles pour marquer l'incrémentation, mais c'est bien les trois espaces avant la sous-liste qui désigneront l'incrémentation. Comme tel : -``` +```markdown + Liste 1 + Liste 2 + liste 3 @@ -204,7 +194,7 @@ Ce qui affichera : * Liste 5 + liste 6 -## Les tableaux +## Les tableaux Pour créer un tableau, il faut utiliser la barre verticale `|` et les tirets `-`. Il est obligatoire d'ajouter une ligne de tiret sous la première ligne du tableau. Il n'y a aucune contrainte dans la taille de ce dernier. Il est possible de formater le tableau avec les `:` dans la seconde ligne du tableau, trois options s'offrent à vous : @@ -212,7 +202,7 @@ Pour créer un tableau, il faut utiliser la barre verticale `|` et les tirets `- |:-------------------------|:---------------:|-------------------------:| |`:-----` | `:----:` | `-----:` | -``` +```markdown | **Un tableau** | Une colonne | Une seconde | Autant que l'on veut | |:--------------:|:-----------:|:-----------:|:--------------------:| | Une ligne formatée | | Et du **texte en gras** | Ou en *italique* | @@ -225,15 +215,15 @@ Ce qui afficherait ça : | Une ligne formatée | | Et du **texte en gras** | Ou en *italique* | | D'autres lignes | |![une image](/images/cd.jpg) | [Ou un lien]( contributordoc) | -## Bloc de codes +## Bloc de codes Pour afficher du texte en brut, des `blocs de codes` peuvent être créer en utilisant l'accent grave `Alt Gr + è` : -```` +````markdown Soit inline, par exemple pour mettre en valeur une touche comme `Ctrl` ``` ou directement en bloc. -La seule différence est dans la quantité d'accents graves : +La seule différence est dans la quantité d'accents graves : Minimum trois accents graves en ouverture et fermeture de bloc et deux accent grave qui encadre le morceau de texte à formater dans une ligne Ce qui donnera au rendu : @@ -246,7 +236,7 @@ La seule différence est dans la quantité d'accents graves : Minimum trois accents graves en ouverture et fermeture de bloc et deux accent grave qui encadre le morceau de texte à formater dans une ligne ``` -## Liens utiles +## Liens utiles + La documentation du langage originel Markdown : [daringfireball.net/projects/markdown (en)](https://daringfireball.net/projects/markdown/) + Tutoriel Markdown sur [markdowntutorial.com (en)](https://markdowntutorial.com) diff --git a/doc_use_git.md b/doc_use_git.md index 968db224..bc875f29 100644 --- a/doc_use_git.md +++ b/doc_use_git.md @@ -1,25 +1,14 @@ -# Propel a contribution with Git - - **Index** - - [Creating an account on github.com](#CreationAccountGithub) - - [Fork the YunoHost documentation into your personal repository](#ForkerDocumentationYunoHost) - - [Edit files and add your contributions](#EditAddContrib) - - [Send your contributions with a Pull Request](#SendPR) - - [Track your contribution and take into account feedback from contributors](#TrackContributions) - - [Bringing up errors and wishes by creating a way out](#RemonterIssues) - - [Correct and Inspect Contributions](#ReviewContrib) - - [Going further with Git and working locally on his computer](#PlusLoinGitOrdi) - - [Some web resources](#WebLinks) +# Propel a contribution with GitHub It is of course possible to contribute directly to the YunoHost documentation, but this is not the most convenient way to do so for both the contributor and the person who will inject your contribution into the documentation. Here is a tutorial to understand and create a contribution to the Yunohost documentation using [Git](https://git-scm.com/) and [github.com](http://github.com/) which is the Git forge service that hosts and stores the YunoHost source code and documentation. -## Create an account on github.com +## Create an account on github.com To be able to send your contributions via GitHub, you need to have an account on GitHub, to create the account you will need a valid email address that you have access to. GitHub is a powerful tool with many features, the interface can be a little scary at first. You don't have to give your first and last names, you can use a nickname (when you register `Username`). */iframe video create a GitHub account /* -## Fork the YunoHost documentation in your personal repository +## Fork the YunoHost documentation in your personal repository To fork the source code allows you to create a new branch of development of a software source code or in this case the source code of the documentation. By creating a new branch, this allows you to modify the code and add your contributions without altering the code of the `master' branch, which is the public release of the documentation. This allows you not to have to write down everything at once, but to do it in several steps. (Especially for contributions that require more time). Forking a project on GitHub is extremely simple, just click on the Fork button, this will create a new repository on your GitHub account. @@ -33,28 +22,28 @@ In the title of the new repository, you will see where the repository comes from > If you forge the repository of another contributor than yunohost, you'll get the same files. Except that when you send your changes, they will be sent to the contributor and not to the yunohost repository. The advantage is that it allows you to develop another branch created by the contributor and work with another person on an improvement before submitting it to the main repository. > It is not possible to have a fork from a contributor's repository and the original repository fork at the same time in your own account. -## Modify and add your contribution +## Modify and add your contribution Once the repository is forked (copied), you will need to create a new development branch within your repository. It is through this branch that you will modify the files and thus propose improvements to the documentation. The fact that it is a new branch will allow you to make a Pull Request, i.e. a request to add your contributions to the `master' branch, which is the main documentation branch. The development rules on GitHub change depending on the developers of each repository, some have a testing branch in which to offer contributions. More information on what a branch on git-scm.com is: [Branching with Git - What a branch is](https://git-scm.com/book/fr/v1/Les-branches-avec-Git-Ce-qu-est-une-branche). */iframe video edit files add contribution /* -## Send your contribution by a Pull Request +## Send your contribution by a Pull Request Create a Pull Request when you want to share your work with the other contributors and integrate it into the master repository (Yunohost's main repository). When publishing a Pull Request, commonly called PR, contributors will be able to amend, comment, add, correct your contribution before it is fully integrated into the repository. -## Track your contribution and take into account feedback from contributors +## Track your contribution and take into account feedback from contributors When you've already create a Pull Request (PR), changes to your development branch in the Git repository will automatically be added to the PR. This doesn't require any additional action. You can also include proposed changes from contributors, who, when they audit the code, may find errors or new, better wording. -## Bringing up mistakes and wishes through issues +## Bringing up mistakes and wishes through issues YunoHost has a specific Git repository to collect issues: [github.com/YunoHost/issues](https://github.com/YunoHost/issues) An issue, also called a ticket, is an identified problem or a development wish; in this case for documentation, but it is valid for any software repository. Within the framework of the YunoHost documentation it will be mainly proposed issues for the development of the documentation, the identified problems being easily correctable. -## Going further with Git and working on his workstation +## Going further with Git and working on his workstation Using the power of Git to work on your personal computer means you don't have to create a `commit' each time you save modified documentation pages. It also allows you to use tools and software that make it easier to distinguish between tags used in a documentation page. - Online resource: [docs.microsoft.com - Setting up a Git repository locally for documentation](https://docs.microsoft.com/fr-fr/contribute/get-started-setup-local) -## Some resources elsewhere on the net to go further +## Some resources elsewhere on the net to go further - [Managing your code with Git and GitHub - openclassrooms.com](https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github) - [Git User Interface - git-scm.com](https://git-scm.com/download/gui/linux) diff --git a/doc_use_git_fr.md b/doc_use_git_fr.md index faa2d579..3590179b 100644 --- a/doc_use_git_fr.md +++ b/doc_use_git_fr.md @@ -1,26 +1,15 @@ # Propulser une contribution avec Git -**Index** - - [Création d'un compte sur github.com](#CreationCompteGithub) - - [Forker la documentation de YunoHost dans votre dépôt personnel](#ForkerDocumentationYunoHost) - - [Modifier les fichiers et ajouter vos contributions](#ModifAjoutContrib) - - [Envoyer vos contributions avec une Pull Request](#EnvoyerPR) - - [Suivre votre contribution et prendre en compte les retours des contributeurs·trices](#SuivreContributions) - - [Faire remonter des erreurs et des souhaits en créant une issue](#RemonterIssues) - - [Corriger et inspecter les contributions](#ReviewContrib) - - [Aller plus loin avec Git et travailler en local sur son ordinateur](#PlusLoinGitOrdi) - - [Quelques ressources sur le web](#LiensWeb) - Il est bien sûr possible de contribuer directement sur la documentation de YunoHost, mais ce n'est pas la manière la plus pratique de le faire tant pour le/la contributeur·trice que pour la personne qui va injecter votre contribution dans la documentation. Voici un tutoriel pour comprendre et créer une contribution à la documentation de Yunohost en utilisant l'outil [Git (en)](https://git-scm.com/) et [github.com](http://github.com/) qui est le service de forge Git qui héberge et stocke le code source de YunoHost ainsi que sa documentation. -## Création d'un compte sur github.com +## Création d'un compte sur github.com Pour pouvoir envoyer vos contributions via GitHub, il est nécessaire avoir un compte sur GitHub, pour créer le compte vous aurez besoin d'une adresse email valide à laquelle vous avez accès. GitHub est un outil puissant qui propose de nombreuses fonctionnalités, l'interface peut être un peu effrayant au début. Vous n'êtes pas obligé·ée de donner vos noms et prénoms, vous pouvez utiliser un pseudonyme (lors de l'inscription `Username`). */iframe video creer compte GitHub /* -## Forker la documentation de YunoHost dans votre dépôt personel +## Forker la documentation de YunoHost dans votre dépôt personel Forker le code source permet de créer une nouvelle branche de développement d'un code source de logiciel ou dans le cas présent, le code source de la documentation. En créant une nouvelle branche, cela vous permet de modifier le code et d'ajouter vos contributions sans altérer le code de la branche `master` qui est le rendu public de la documentation. Ce qui vous permet de ne pas devoir tout marquer mais le faire en plusieurs étapes. (Notamment pour les contributions demandant plus de temps de travail). Forker un projet sur GitHub est extrêmement simple, il suffit ce cliquer sur le bouton Fork, cela créera un nouveau dépôt sur votre espace de GitHub. @@ -30,33 +19,32 @@ Dans le titre du nouveau dépôt, vous verrez de quelle provenance vient le dép */iframe video forker code source GitHub /* - > **Point de vigilance !** > Si vous forkez le dépôt d'un autre contributeur que yunohost, vous aurez les mêmes fichiers. Sauf que quand vous enverrez vos modifications, elles seront envoyées au contributeur et non au dépôt yunohost. L'avantage est que ça vous permet de développer une autre branche créee par le contributeur et ainsi travailler avec une autre personne à une amélioration avant proposition au dépôt principal. > Il n'est pas possible d'avoir un fork du dépot d'un contributeur et le fork dépôt d'origine au même moment dans votre propre dépôt. -## Modifier et ajouter votre contribution +## Modifier et ajouter votre contribution Une fois le dépôt forker (copié), il faudra créer une nouvelle branche de développement au sein de votre dépôt. C'est à travers cette branche que vous allez modifier les fichiers et ainsi proposer des améliorations de la documentation. Le fait que ce soit une nouvelle branche vous permettra par la suite de faire une Pull Request, c'est à dire une demande d'ajout de vos contributions au sein de la branche `master` qui est la branche principale de la documentation. Les règles de développement sur GitHub change selon les développeurs de chaque dépôt, certains ont une branche testing dans laquelle il faut proposer les contributions. Plus d'informations sur qu'est une branche sur git-scm.com : [Les branches avec Git - Ce qu'est une branche](https://git-scm.com/book/fr/v1/Les-branches-avec-Git-Ce-qu-est-une-branche). */iframe video modifier fichiers ajouter contribution /* -## Envoyer votre contribution par une Pull Request +## Envoyer votre contribution par une Pull Request Faire une Pull Request correspond au moment ou vous souahitez partager votre travaille avec le reste des contributeurs⋅trices et l'intégrer au dépot master (dépôt principale de Yunohost). Lors de la publication d'un Pull Request, couramment nommé PR, les contributeurs⋅trices pourront amender, commenter, ajouter, corriger votre contribution avant intégration complète au dépot. -## Suivre votre contribution et prendre en compte les retours des contributeurs·trices +## Suivre votre contribution et prendre en compte les retours des contributeurs·trices Lorsque vous avez déjà fait une PR (Pull Request), les modifications de votre branche de développement sur le dépôt Git se rajouteront automatiquement à la PR. Cela ne nécessite aucune action supplémentaire. Vous pouvez aussi intégrer les propositions de modifications de contributeurs, qui lorsqu'ils/elles auditeront le code, peuvent trouver des erreurs ou de nouvelles formulations plus adaptées. -## Faire remonter des erreurs et des souhaits par des issues +## Faire remonter des erreurs et des souhaits par des issues YunoHost dispose d'un dépôt Git spécifique pour le recueil des issues : [github.com/YunoHost/issues](https://github.com/YunoHost/issues) Une issue aussi appelé ticket, est un problème identifié ou alors un souhait de développement ; dans le cas présent pour la documentation, mais c'est valable pour tout dépôt logiciel. Dans le cadre de la documentation de YunoHost il sera surtout proposé des issues pour le développement de la documentation, les problèmes identifiés étant facilement corrigeable. -## Aller plus loin avec Git et travailler sur son poste de travail +## Aller plus loin avec Git et travailler sur son poste de travail Utiliser la puissance de Git et ainsi travailler sur son ordinateur personnel, permet entre autres de ne pas avoir à créer de `commit` à chaque enregistrement intermédiaire des pages de documentations modifiées. Cela permet aussi d'utiliser des outils et logiciels qui permettent une distinction plus facile des codes utilisés dans une page de documentation. - Ressource en ligne : [docs.microsoft.com - Configurer un référentiel Git localement pour la documentation](https://docs.microsoft.com/fr-fr/contribute/get-started-setup-local) -## Quelques ressources ailleurs sur le net pour aller plus loin +## Quelques ressources ailleurs sur le net pour aller plus loin - [Gérer son code avec Git et GitHub - openclassrooms.com](https://openclassrooms.com/fr/courses/2342361-gerez-votre-code-avec-git-et-github) - [Interface utilisateurs·trices de Git - git-scm.com](https://git-scm.com/download/gui/linux) diff --git a/doc_writing_guide.md b/doc_writing_guide.md index ec2e62da..14d64208 100644 --- a/doc_writing_guide.md +++ b/doc_writing_guide.md @@ -1,37 +1,39 @@ # Guide to writing application documentation -## Pages for user / administative documentation +## User documentation pages / administrateurs⋅trices -Add a one-click installation button (like for example: https://yunohost.org/#/app_piwigo) +Add a one-click install button (such as https://yunohost.org/#/app_piwigo_fr) and a button on the application integration level. -Classification of the application can be done using the available tags (genre, Git, management association, e-mails, etc.) -*/Find a suitable documentation license. Permissive or not? (CC BY_SA)/* +Classification of available applications by tags (genre, Git, association management, emails, etc.). -## Clarify the types of uses it has (special and general application (editorial choice) +*/Definition of a license to distribute the documentation, but which one? Permissive or not (CC BY-SA)/* - + For links to other languages, add (en)` for Egnlish, and so on. +## Some typical and general uses (writing framework) -### Things to include in application documentation + + When a link points to a page that is not in the language of the original page, it is customary to add `(en)` (for a link that points to a page in English). + + rename the images in the following order:`description_application.ext`. - 1. An index of what is included, without reiterating the full content of what is to be found in subsequent chapters. - 1. A one-click install button. +### General frame application documentation + + 1. Logo (dimension 80 pixels high) + level 1 title. + 1. One-click install button, Integration level for each type of processor. + 1. An index at the top of the documentation with cross-references to all the chapters of the documentation. 1. A general presentation of the application and its function. - 1. A section detailing administration of the application. - 1. A further section on changes specific to YunoHost. - 1. A section about the desktop client (if applicable). Links to different third party applications (if they exist), (or a link to a list of applications [framalibre.org](https://framalibre.org)) or a link to a page that has to do with the different official applications (if applicable). - + A further section: - - Links to the official website. - - Links to the package in YunoHost. - 1. Documentation of any further uses (documentation of an application). + 2. A configuration part of the application. + 1. An administration part of the application. + 1. A part on limitations related to YunoHost. + 1. A part on desktop clients (if any). A link to different third-party applications if there are several (possible link to the applications catalgue [framalibre.org](https://framalibre.org)) or a link to the page about desktop applications if official applications are provided. + 1. A part with : + - the link to the official site + - the link to the documentation + - Links to the YunoHost package and issues + +Screen for writing documentation pages: [here](/app_writing_guide) ## Roadmap -1. Documentation of the applications. - 1. Document how the application operates in use (marked: work) level 8/7/6. - 1. Translate the documentation at-least into French and English. - 1. Send a PR to the repository of the app that details its documentation. - -## Document an application - -Do you need to detail how it works? +1. Document applications. + 1. Document applications at work (marked: work) level 8/7/6. + 1. Translate the documentation page at least into French and English. + 1. Do a PR on the application repository diff --git a/doc_writing_guide_fr.md b/doc_writing_guide_fr.md index c04910fa..f62f3598 100644 --- a/doc_writing_guide_fr.md +++ b/doc_writing_guide_fr.md @@ -2,7 +2,8 @@ ## Pages de documentations utilisateurs.trices / administrateurs⋅trices -Ajouter un bouton installer en un clique (comme par exemple : https://yunohost.org/#/app_piwigo_fr) +Ajouter un bouton installer en un clique (comme par exemple : https://yunohost.org/#/app_piwigo_fr) et un bouton sur le niveau d'intégration de l'application. + Classement des applications disponibles par tags (genre, Git, gestion associations, courriels, etc.). @@ -16,18 +17,19 @@ Classement des applications disponibles par tags (genre, Git, gestion associatio ### Trame général documentation applications 1. Logo (dimension 80 pixels de hauteurs) + titre de niveau 1. - 1. Bouton installer en un clique, Niveau d'intégration, et le status. + 1. Bouton installer en un clique, Niveau d'intégration pour chaque type de processeur. 1. Un index en tête de documentations avec renvois vers l'ensemble des chapitres de la documentation. 1. Une présentation général de l'application et de sa fonction. + 2. UNe partie configuration de l'application. 1. Une partie administration de l'application. - 1. Une partie aller plus loin, Manipulations techniques, liés spécifiquement à YunoHost mais aussi les limitations. + 1. Une partie sur les limitation liés à YunoHost. 1. Une partie sur les client desktop (si il en existe). Lien vers différentes applications tierces si il en existe plusieurs (lien possible avec le catalgue d'applications [framalibre.org](https://framalibre.org)) ou un lien vers la page concernant les applications desktop si des applications officiels sont fournis. - 1. Documentation de l'utilisation si besoin (cf. Documenter une application). 1. Une partie avec : - - les liens vers le site officiel - - Les liens vers le package de YunoHost + - le lien vers le site officiel + - le lien vers la documentation + - Les liens vers le package de YunoHost et issues -Trame markdown pour la rédaction des pages de documentations : [ici](/app_writing_guide_fr) +Trame pour la rédaction des pages de documentations : [ici](/app_writing_guide) ## Feuille de route @@ -35,33 +37,3 @@ Trame markdown pour la rédaction des pages de documentations : [ici](/app_writi 1. Documenter les applications au travail (marqué : work) niveau 8/7/6. 1. Traduire la page de documentation à minima en français et en anglais. 1. Faire une PR sur le dépôt de l'application concerné vers la page de documentation. - -## Documenter une application - -Faut-il documenter son utilisation ? - -``` -La documentation de l'application est elle disponible en français & en anglais ? - / \ - / \ - / \ - / \ - / \ - ------- ------- - | Oui | | Non |----> Documenter l'application <----<----<----<----- - ------- ------- dans la documentation de YunoHost | - | | - La documentation utilisateur est elle de bonne qualité et suffisante ? | - / \ | - / \ | - / \ | - / \ | - / \ | - ------- ------- | - Renvoi dans la page de doc ------- | Oui | | Non |---->---->---->---->---->---->---->---->---->---->---->---->---->- -YunoHost vers le site officiel ------- ------- -``` - -## Potentielles problématiques rencontrés ? - -Quid des applications qui sont des containers à d'autres applications, tel que Nextcloud et qui présentes de multiples possibilités d'usages.