New Documentation Hub


#1

Per conversations with @eliotberriot and interactions in the help chatroom, I am going to be looking at a rewrite of the documentation hub. I would like to include the following features:

  • Guides for administrative tasks such as using Django Administration
  • Guides for user actions such as tagging/managing music and using third party apps
  • Troubleshooting guides for users/admins

Currently, all documentation is in one place, which means that things can get a bit cluttered and difficult to find. I would propose that we look at splitting this up into instance admin guides and end user guides so that each type of user can get the best support possible.

If anybody has any suggestions, I would be happy to hear them. Particularly I would like to see wider language support as currently all docs are in English. Please feel free to leave suggestions in this forum or to contact me on Riot/Matrix or by email


#2

That’s a very good idea, I think.
Perhaps also separate the installation guide from the administration guide.
We would have 3 guides: Installation, administrator, user.


#3

I agree. We may have several admins/moderators on an instance but only one person managing the server. Subdividing may be useful in that instance.


#4

The way I see it, we have:

  • Regular users
  • Administrators (people doing the deployment/tech stuff)
  • Managers/moderators who have specific, non-technical tasks to do that are not accessible to regular users (changing the configuration, blocking other instances, moderating content, creating invitations, etc.)

#5

Installation and upgrade docs should be kept in their own section, I think. Am I right in thinking that moderators do not necessarily have access to the backend? If that’s the case, we would need to have:

  • Installation/Upgrade/Maintenance guides for Operators
  • Django stuff kept in with Operators/Admins
  • Frontend stuff for mods
  • General User Guides

#6

Absolutely :slight_smile:

Another option is to have three main sections in the documentation (one for each type of user I mentionned earlier), and split those sections in “Guides”, “Tutorials”, “Explanations”, and “Reference”. (https://www.divio.com/blog/documentation/ describes a bit more what is the goal of each one)

This is a bit boring, but this is apparently an effective way to structure documentation for big projects, and I have the feeling it would make maintenance considerably easier by forcing up to think up-front about the type of documentation we’re writing, and for who we’re writing it.

It could look like this:

  • User documentation:
    • Tutorials: creating your first account, using DSub, tag your music, upload your music, follow a remote library, etc.
    • Explanations: how does Funkwhale work, what is the federation, etc.
    • References: what tags are supported in files, list of available third-party apps, etc.
    • Guides: troubleshoot errors and issues, etc.
  • Operators/moderators documentation:
    • Tutorials: configure your instance for the first time, invite someone, block a remote instance, etc.
    • Explanations: how does moderation work within Funkwhale, how to avoid copyright issues, etc.
    • References: what is the meaning of each configuration option in the settings UI
    • Guides: troubleshoot common issues, etc.
  • Admins documentation:
    • Tutorials: deploy Funkwhale in 5 minutes via our docker container, import music from the server via the CLI, etc.
    • Explanations: what are the components required/used by funkwhale, how is music managed, etc.
    • References: what are the settings/environment variables and their meaning
    • Guides: Install funkwhale on various platforms, troubleshoot common issues

Actually, I can also think of a 4th category of person with different interests: developers who need to integrate with Funkwhale: app developers, people interested in our APIs, etc.


#7

I agree. It makes later changes much easier to perform. It may seem a bit much at first, but as the number of guides grow it’s going to be a lot easier to chop and change multiple small sections than fewer big ones.

The next question is: is Gitlab still the best place to host this? What tools do they have wrt translations?


#8

I do think the documentation should be along the code, for a really simple reason: not everyone use the same version of Funkwhale at the same time, and the documentation will change from one version to another. Using one version of the documentation with the wrong version of your server is likely to end up in difficult, hard to debug issues, especially regarding to deployment.

By versionning the documentation with the code, we are able to have the documentation matching a specific version, and serve various versions of the documentation in parallel (if we choose to do so). It’s also possible to bundle the documentation with Funkwhale releases, so that each deployed instance have a copy of the documentation available, and served at yourdomain.funkwhale/docs/, for instance.

I realize it makes it harder to contribute to the documentation though, but maybe we can find a way to make that easier (by sharing tutorials on how to fix typos in the documentation via Gitlab’s Web IDE, for instance)?


#9

I forgot to answer about the translation part, but it’s more of a Sphinx-related issue for me (and apparently, Sphinx does support translations


#10

Ah, okay! I’m fine keeping things in Gitlab, and agree about versioning. If we can get translations working, we’ll be in a good position.


#11

Looking at that document, there is some work to do around getting Sphinx set up for translations and possibly more steps in each new creation/edition of an article.


#12

how about an api documentation ?


#13

@a7medo778 indeed, the API documentation should probably be included in the developpers section of the new hub. (In the meantime, you can access it here, even if not all endpoints are already documented)


#14

Yeah, it would be good to have all of that info in one place. I’m going to start doing a bit of rewriting/restructuring over this week, so I’ll also start porting what’s currently in Swagger over so it’s all in one place.


#15

@sporiff do you mean rewriting the API documentation in Sphinx? I’m not sure we can reach the same level of documentation with sphinx as the Swagger thing is interactive and you can try the API in real time while browsing the documentation


#16

Just as an update to this: there is now a WIP pull request open where I will be doing some work on restructuring current content and creating new guides/documents where I can.

Apologies for moving so slowly on this. Been a bit snowed under at work.


#17

I’ve added several new guides to the user/moderation sections of the documentation in !661. I’ve done some moving around of content to try and make it feel a bit more natural for new users coming in to the project. If anybody has any further suggestions for guides/changes to what I’ve already done, please let me know. I have a few other things I’d like to get written down, but that will probably have to wait for tomorrow.


#18

@sporiff I’ve had a round of review on your pull request, and this is really good work. I’m excited to see this deployed! My comments are relatively minor things which should be easy to fix, let me know if you need help with this :slight_smile: