What is missing in the doc ? / Qu'est ce qu'il vous manque dans la doc?

Contribute Room
,
1

That’s an open question to all yunohost users.

C’est une question ouverte pour l’ensemble des utisateurs et utilisatrices.

3 Likes
2

I’m going to reference a GitHub issue Reply by the Firefly III author on wanting to contribute to the YunoHost Package here

Installing Yunohost is pretty straight-forward, although the certificate handling code feels messy. But no matter. I can install and run Yunohost locally.

Then, I want to start deploying my own app. First page I run into is this one. It’s messy and convulted. It does not provide a summary or a starting point. You’ll have to read it entirely to understand what it’s about, you can’t scan the content. It needs four massively long paragraphs to explain the fact that user input is used for the scripts and then starts to explain what bash is. If I’m reading an introduction to packaging you can assume I know what I’m talking about. So skip explaining what bash is.

Give me a high level overview of the process:

* Script defines user input.

* User input is put into install script.

* Install script does its shit.

* User has application.

Then point me to the relevant help sections where I can find info on each step of the process.

The bash tutorials point to something outside of your domain, in French, so this is useless for the majority of your audience (because unlike what most French people seem to think, not everybody speaks French).

The app packaging page is more promising. It starts with requirements, the content of a package and a basic package. Again a useless link to a French page about Virtualbox though.

The example package is a bit confusing since it’s readme file is both the instructions on how to use the example, AND it’s an example readme file. But alas.

So once you clone the example app you open the install script to see what you need to do. Lots of magic here. The arguments from the manifest seem to make sense, but then there’s a lot of stuff about one of the Yunohost’s helpers that I don’t think I need at that moment. The helpers should be explained on a dedicated page (just the fact that there are helpers isn’t explained anywhere).

It continues with stuff about nginx or your own webserver but most importantly, there is nothing on the architecture of anything.

At this point I’m head first into an installation script with very little context. I already deduced that packages share the system, so whatever I install is installed for all other packages. There are helpers for all kinds of things too.

But this is the moment where I would want to kick off my installation script, just to see what happens. The documentation points to a dev package where I find scary stuff like “The following commands should work”… I mean, It’s a dev package in the Yunohost GitHub space, surely it will work? Nothing worked by the way and the use case of this dev thing isn’t clear to me.

So now I have some install script and no way to run it. The help text simply says: run su - admin -c "/bin/bash /path/to/my/script my_arg1 my_arg2" to run it but nowhere is explained how I can get my script inside of the Yunohost. I’m not going to commit every test over git so no option remains.

So just to explain how I got here took me about an hour, including the installation of Yunohost itself.

When I first started I gave up half-way until @anmol26s went through this nightmare and did it for me. But for the life of me I couldn’t update this script if I wanted to.

3 Likes
3

Je suis assez d’accord avec @elikoga, j’ai aussi mis pas mal de temps à comprendre le système de packaging, même en lisant la page dédiée et en m’inspirant d’un paquet existant.
Je n’ai compris certains concepts et me suis rendu compte de certaines erreurs que plusieurs semaines après avoir commencé le paquet.
Je pense qu’il faudrait un exemple détaillé et commenté, ceci-dit je sais que l’exercice est très compliqué et qu’il y aura toujours des gens insatisfaits.

Pour ma part c’est vraiment le seul point qu’il m’a posé problème, les autres sections m’ont paru parfaitement claires, surtout celle sur la messagerie et les DNS, je m’attendais à quelque chose d’extrêmement compliqué et risqué et j’ai été agréablement surpris par la facilité et l’efficacité du processus, grâce à la doc.

3 Likes
4

I think the very insistent francophone community should also be mentioned somewhere more prominently in the documentation - I was surprised by a fully French e-mail today I received just because @bleeh decided to mention me. The documentation should reflect that.

6

I think the documentation under https://yunohost.org is very good. But in bad structure… It’s hard to find the real information :frowning:

e.g.: “What is YunoHost?” is very good: YunoHost • index

But it’s too much hidden. Like many other good sites. Probably people do not find that.

Think this page should be seen if you scroll down.

IMHO the homepage is nice for mobile surfing. But bad for normal desktop browser. Think a main navigation is missing and the JavaScript only “back” function is broken, if you open links in tabs.

1 Like
7

Yup there’s some ongoing work by @tituspijean to migrate the documentation to Grav (and the idea itself dates from a couple years now) … Hopefully we’ll be able to finish this at some point soon™ :s

3 Likes
8

Duely noted @jedie, thanks for the heads up, I totally agree. :wink:

I took the liberty of pinning this thread and moving your post over here, to have a common thread about documentation improvement.

2 Likes
9

Hello,

  1. Pour les admins : Je trouverai intéressant d’avoir le process pour installer Yunohost sur disque externe et donc boot sur USB (pour RPI)

  2. Pour les contributeurs : De la doc sur l’installation et l’utilisation de NodeJs (actuellement il faut aller chercher dans le les repos de package d’autres applications pour essayer de comprendre comment ça marche)

–

  1. For admins : I will find interesting to have the process to install Yunohost on external disk and then boot on USB. (for RPI)

  2. For contributors : From the doc on the installation and use of NodeJs (currently you have to look in the package repositories of other applications to try to understand how it works)

1 Like
10

That is a very nice question!

Two things I see as substantial potential improvements which lower the bar for administering Yunohost on a Raspberry Pi:

1. Getting the GUI into - and the terminal use out of - the onboarding guidance/documentation

A concrete example of where this is currently done is: Advertise the use of yunohost.local for install @ homes by alexAubin · Pull Request #1491 · YunoHost/doc · GitHub

2. Re-thinking the best setup(s) for small scale serving, and creating a fitting onboarding experience

The best case here would be if the docs are used as little as necessary and users are guided within their yunohost installation most of the time:
To use a quote from a post from two years ago to illustrate the issue for new administrators:

General notes on Yunohost UX and documentation

As a UX researcher, my view on documentation is this: when documentation is needed to solve an issue, then that is a sign that the UX of the product itself is probably flawed on the matter.
Now, the overarching goal for Yunohost, as I understand it, is to get more of the worlds server infrastructure from big clouds and into people’s own control. The method of Yunohost is basically to ask: “Why do you not host yourself?” literally, record the answers that people give, and then addressing those issues to make it easier. It is best is not to ask seasoned admins and devs, but people with almost no knowledge about administering a server. If we do this, then we will know what needs to be added to Yunohost, or if we don’t want to change something in the UX, to its documentation. And it will be awesome :smiley:

Cheers!

1 Like