Call for feedback on a rework of the documentation

Hey there !

Following the impulse of @tituspijean and @ljf, a “documentathon” was organized this weekend to work on the documentation :partying_face: :computer:. In particular :

  • :building_construction: the documentation was ported to Grav to finally have some much needed features like a navigation sidebar and being able to search the doc
  • :rocket: refactorize the install documentation to avoid splitting all the different steps into many different pages
  • :space_invader: misc small refactorings / cleanups

The current version is still being polished but quite a lot of progress has already been made ! We are looking for feedback from the community and planning to release this new version around the end of the week.

https://yunohost.org/docbeta

N.B. : the new install process documentation is not translated yet (and still being polished) - be sure to use the english version when looking at it. Many other pages still may need some cleanup / rework as well.

Cheers !

18 Likes

already looks better than the old version!

Yeahh looks really nice ! It seems to be handy. I will have a better look soon.

Just one feature request : I don’t know if it’s relevant or feasible, but is there a way to get a dark mode on this documentation ?

1 Like

It seems to be feasible: Adding dark mode swicher to Grav | Louis Charette

1 Like

Thanks to @Kayou @frju365 @Aleks for their help too. :slight_smile:

1 Like

Great job! I surprised myself reading the doc :slight_smile:

4 Likes

We could indeed investigate having a dark mode, but first can you check out the Dark reader browser extension? It has worked greatly for me on PC and mobile, and it themes automatically (and surprisingly well) all the sites. :wink:

3 Likes

Oh yes, I had installed it several years ago, but there where some sites which didn’t work. I will try again now, thanks :smiley:
But IMHO, it’s always better to implement the feature on the site itself in place of make it possible by an extension.

Lazy/incompetent coder with no web design skill speaking: buuuuuut if an extension can do the job for you… ¯\_(ツ)_/¯.

I do agree we can add the feature to the to-do list. :innocent:

1 Like

Looks amazing and it seems much easier to navigate, thanks for the work!

2 Likes

The new dark mod is deployed.

There may be some cache problems on already visited pages. You can empty the browser’s cache, or force the cache refresh with ctrl + shift + R.

5 Likes

Whaouw, it’s beautiful !! Thanks very much !! It’s perfect ! :partying_face:

Annnnnnd the new documentation is live !

8 Likes

Looks great !
I think it would just need a bit more hierarchy on the “Specific use case” part, which is a little bit messy
Other than that, it looks way better than the older one indeed, thanks !

Brainstorm mode on: maybe we could drop the listing on the side pane, since there is no real/clear hierarchy between these use cases, and have a nice presentation page on the main page Specific use cases | Yunohost Documentation.

Looks great! Thanks a lot. Just one wish: I can hardly see the scrollbar in the left menu. Nearly invisible and so thin!

And one suggestion: What about an updated and noob-friendly documentation of (automatic) backup to remote server and restore? So far I have done it manually with the web ui and now was looking for a smarter way to do this, especially with incremental backups with Borg or Restic (not sure about Archivist as this app is unmaintained). The documentation just links to forum threads that seem to be outdated and incomplete and Restic is not mentioned. The readme of the available backup apps do look scary to me, like that it would be easy to do things wrong and mess things up. What do you think? Thanks!

EDIT: Or maybe a simpler solution combining rsync to remote server with automated in-built backup?

EDIT2: Or make a script based on this example? VPS backups are simple—you’re just overthinking it | Serverwise

2 Likes

It looks nice! I like the tab feature within pages.

Harmonica/collapse-expand sections

Is there also a harmonica/expansion feature of some kind? If a user is in an install flow then linking to other pages and forum posts takes them out of the flow, which is confusing. It would be much less confusing to be able to keep them on the page but offer an explanation in an expanding section on a click on a certain link.

Usable backup is crucial (core)

And I very much agree with all of the comments of @TheNomad11 in the above. I perceive usable backup guidance/solutions as the last frontier for usability of Yunohost. I have not dared using my Yunohost instance beyond TinyRSS basically. When I currently answer the question “Why you no host (documents and other files)?” the only reason left is: “Because I’m scared I will lose days or much more of writing/editing work by server failure/theft/fire/hacking”. To get a Yunohost server production-ready for storing and editing files, music etc. etc. a usable and reliable backup solution is most important. Otherwise users are taking great risk in loosing lots of work in case of failure. Some important features of this backup feature I can imagine to be general user-centric design, and more specifically: automated, remote/local, encrypted, incremental, verified, easy restoring.

In fact, usable backup and restore is so core to administering a server that we should strive to implement a usable backup feature within Yunohost admin itself. Instead of relying on other apps. That is because we don’t have much influence on the other apps and they often lack good usability or maintenance. Good documentation is a good first step to get a grip, but in the end, all crucial functionality should be usably offered within Yunohost - or less preferably: in highly usable documentation walk-throughs.

1 Like

Hello,

Thanks for your work on documentation!

I noticed unexpected behavior on documentation when using search or advanced search.

Simple search

Doesn’t seem to work well on my side.

Advanced search

If I do an advanced search on “revers”, I got several results for “reverse”.
If I add an extra “e” to my search, I only get one result.
I expect to find all pages with “reverse”.

Hello!
Thanks for your feedback.

Can you share your criteria for “working well”? :stuck_out_tongue:
In my experience, and comparing with Grav’s own documentation, I do agree something feels off with this search box. Typing into it should expand the page hierarchy and display which pages contain the text you are typing. Without that, it is pretty useless.

It feels like incomplete indexing, though at least one other person is complaning about similiar behaviour: Irregular results · Issue #114 · trilbymedia/grav-plugin-tntsearch · GitHub

Hello @tituspijean,

Sorry for this short description.
When I tried to use simple search box, I enter a keyword and hit enter and top menu doesn’t uncollapse to show you results.
If I uncollapsed top menu, I got my results.

I look into web browser console and there is an HTTP request sent with a results in both cases.

In fact, it seems that simple search act as filter on sections in documentation which it is a bit counterintuitive.