I wrote the vast majority of Funkwhale's user-facing documentation a couple of years ago when I was still quite naïve to technical writing. For this reason, it's starting to show its limitations a bit now.

Since then it's not really seen enough love and several things about it probably need to be updated and enhanced:

  • Language needs to be simplified to accomodate users who don't speak English as a first language.
  • Additional frontend features need to be properly documented (preferably with images/video content for visual learners).
  • Frontend and backend need to be properly documented from a developer perspective to aid onboarding.
  • A consistent writing style needs to be employed across all documentation (similar formatting, header language, etc.).
  • Preferably, we should look to add localization to the docs to enable more users to get involved.

This is just a quick thread to summarize my thoughts on the matter. Please feel free to add any suggestions.

gcrk Yeah I've had a look at those changes and they're great 🎉 Huge props to Jovuit for the work.

There's still a lot of stuff I think we need to change, mainly with regards to language consistency and accessibility. I've been doing a lot of this at work recently and it's got me looking through the documentation and thinking of how best to improve it, so I just thought I'd make this post to keep a note of my musings.

    7 months later

    gcrk You can also view the deployed rework directly. Please note that there are still some bits and pieces to be done with the glossary of terms, linking information properly, and general cleanup. Only the User Documentation section has been updated so far, the rest will be done later.

    In particular I'm looking for feedback on the layout, presentation, and flow of information. Plus anything I might have missed. I've tried to rewrite everything in the current documentation while also adding some new content that I felt was missing.

      Okay, so following on from the user documentation rework, I've finished rewriting the moderator documentation. You can check out the deployment here.

      Let me know if you have any feedback!

      When working on the website redesign an issue we identified was a single "documentation" entry point leading to a huge bullet list covering up a broad range of situations. We also thought learning how to use funkwhale and developper resources were two unrelated things, and we figured out exposing documentation topics directly accross the website would help providing people with the information relevant to their situation.

      So like you we went with tiles for introducing the documentation topics, but we chose to integra the them directly inside the website, where we would have a "Help" page and a "Contribute" page. This is how things are going so far.

      I didn't went too deep into reviewing the documentation yet, still I find the changes most welcome! The new "user documentation" hierarchy is much simpler, and the sidebar now gives a clean overview of all funkwhale features. I believe it is a much more effective way to give access to the content, because I find the huge bullet lists of the previous user documentation overwhelming. This is great!

        mjourdan Thank you for your feedback 🙏 Those designs look great! The two will coexist nicely, as we can link directly to the index page of each documentation section (user, moderator, admin, developer, contributor) from the tiles on the website just as we do in the documentation 😀

        The huge bulleted list and the confusing "Features" page are two things I'm really keen to see go, as I don't think this layout helps anybody find what they need or figure out what the software does. There's a more up-to-date preview here which features updates to the moderator documentation and the beginning of our admin documentation overhaul.