Updating the Tidal website and documentation

I'm not in a position to speak for the people involved, but I am confident that at the point of migration all content in the old user base will be brought across - at this point I think they are just working out what solution is going to work best.

TL;DR you are not wasting your effort by contributing doco - and I for one am very grateful, thankyou!

2 Likes

Yep this is moving a bit slow and we'll make clear when the transition is underway.. Thanks @slowleopard!

I will be working on the new documentation website this week:

  • moving content from the old to the new documentation (many thanks to @dowdiness for having worked quite a lot on it already).
  • adding images here and there, more detailled examples when possible (with sound!).
  • creating sections for tutorials/how-tos/references/etc...

I have forked the docs and I will push my updated version very soon. I might do some big structural refactoring from the precedent version. I'm loosely inspired by this approach that @yaxu quoted a few months ago.

I don't want to interfere with anybody else's work, so please tell me if you were already working on the docs so we can share our versions and discuss about it :slight_smile: .

5 Likes

Thanks @raph looking forward to this!

Great, I was going to look into some changes this week, I'll hold off :slightly_smiling_face:

Thanks for all your efforts guys

Nice! Are you interested in using generated code docs as part of your structure? I don't have anything concrete yet, but I did do some research and experimentation based on the prior discussion, and would be interested in helping along those lines.

So far, I've learned that Pandoc doesn't seem too useful, as its Haddock support seems limited to the Haddock syntax for marking up doc comments, rather than the full documentation system. (Perhaps this is for literate Haskell?) The Hoogle output format that Haddock supports seems closer to what would be useful for a doc site, but it might be worth adapting that to develop a Haddock backend that generates JSON data that can be imported by pages on a Docusaurus site. That's a project that I'd be interested in working on, though there'd still be a bit of a learning curve.

Looking forward to seeing what you come up with!

1 Like

Not really. A big chunk of the work for now is just to port/reorganize all the knowledge from the userbase. I also want to find a way to make it really easy to find things depending on what you are looking for: information, tutorials, details, how-tos, inspiration, etc...

I'm also interested in one particular thing that I thought was missing from the current documentation: all the knowledge, tutos and cool code snippets that you can currently find on the forum or on the various chat rooms but that aren't listed or taken anywhere else. Most of the time, these tiny fragments of info are addressing very specific topics that could be interesting for a lot of people, wishing to master and extend Tidal to fit their workflow.

This kind of autogenerated documentation could be interesting in the future for at least two reasons:

  • automatically generate a very technical, very cold but interesting report of the innards.
  • allow people to dive into Tidal, and allow people to understand the system better so they could modify it or contribute.

It might be intereresting to use this kind of autogenerated documentation for the reference section (aka technical side of things).

1 Like

Ok, I am back with some news. Take a look at the new documentation website.

I reorganized and sorted out everything by category, and I have tried to do something that can be quickly browsed. I'll surely continue this week but I would like to gather some feedback first.

  • What do you think about it?
  • How could it be improved?
  • What articles should be created?

EDIT: there are still things to improve (e.g. attributions, credits, etc..) but it will be done. The reference section will be a lot of work too. I think it should be splitted in two: 1) tour of the functions for non-Haskell people 2) detailed reference with codebase documentation.

8 Likes

Wow, this is SOOO much better. Thank you for doing this!

The only thing I miss atm is a prominent search bar, as that's the feature I use most. I might even suggest a search bar in place of the current "Get Started" button.

1 Like

Good point on search! I've applied to the recommended 'Algolia' docsearch service.

Big thanks to @Raph and the others who have worked on this by the way, it's looking amazing!

(Changes to the wiki since the last export need bringing across too)

1 Like

@raph pointed out that some of the functions are only documented in the tidal club course.. So to support the ongoing documentation effort I've opened up the remaining four week block of course materials, so they're all now licensed as CC-BY-SA.

1 Like

Quick update: the section named small reference is now almost complete. It is meant to replace the All the functions page from the old wiki, with its numerous sub-pages. I have tried to organize all the functions in several categories: accumulation, composition, time, sampling, conditions, etc...

It means that you can probably use this website now to get in-depth information about Tidal. It's still a bit rough on the edges but the formatting is better compared to the old wiki.

3 Likes

It's looking fantastic, I can only imagine how much work has gone into it, but it feels like it's making strides forward.

I personally am also a fan of the dark mode - my eyes thank you :smiley:

So far I've only browsed content, do you want us to try out editing as well (and will edits be preserved or is it still in flux)?

I've got a couple of thoughts:

  1. I think the front page should have a video of tidal in action - that classic video of @kindohm in shadow with "oh hai I'm mike!!!!" up top of the page was what actually triggered my "oh shit this just blew my mind open" moment. Given tidal is predominantly used to sequence audio events, using the concept of "code", I think it's really important that both those bases are demonstrated from the outset with a video.

  2. Automation surrounding the recommended version numbers (eg installation page) - I see that the install page is still listing install instructions for Superdirt at v1.1.3(! it's at 1.7.2). What sort of options do we have for automating the process of generating those version numbers? (as a side note, I use the following filter for my installer:

git ls-remote https://github.com/musikinformatik/SuperDirt.git | \
  grep tags | tail -n1 | awk -F/ '{print $NF}'`
  1. Lastly, I'm feeling rather out of place with the inclusion of my yt channel amongst some incredible educators (education not really being a focus of my channel) - but to whoever added it: I'm glad you're able to get some value out of my mistake ridden livestreams!
    (As a heads up, I won't be upset if it gets removed/replaced with something else either :slight_smile: )

Some random ideas off the top of my head that I wouldn't mind contributing to (or reading):

  • collaborative livecoding etiquette (high level, probably better in an article format - this has been discussed on the forums but it would be nice to have a collaborative pool of ideas on the subject)
  • optimising pattern writing style/speed for live performances (I don't do this btw, it's a problem I'd like to solve :smiley: probably better as an article format again, but it'd be nice if it could be collaborative )
  • royalty free samples directory/sources (would probably need some regular maintenance though, so that's a commitment someone will be making)

Hope that's of some value - once again, thanks for all the work pulling this together :slight_smile:

Great job! This looks so much easier to navigate than what came before.

Regarding the search bar, one thing I would love to see is the possibility to add it as a search engine to the browser. I don't know what it takes to do that, but I'm hoping it wouldn't be too difficult.

1 Like

do you want us to try out editing as well (and will edits be preserved or is it still in flux)?

Everything is hosted on GitHub! You can contribute by cloning the repository and adding your changes. Articles are written using the markdown markup language. Note that the editing process can be quite un-intuitive at first but once you understand how to update the sidebar/topbar to include the page you wrote, you will be up and running.

I think the front page should have a video of tidal in action

Yes, I agree. I tried to do it but we might need a JavaScript ninja for that. I'll try again today. I don't know anything about web developement or about JavaScript. Concerning the articles themselves: you can't add videos to a MarkDown page. You can create links, and image links. It means that the best you can do is to trick people by making them click on images that will run the content on YouTube, etc...

Automation surrounding the recommended version numbers (eg installation page) - I see that the install page is still listing install instructions for Superdirt at v1.1.3(! it's at 1.7.2).

Some pages are really outdated and were written a long time ago. That's the nature of the old wiki. I guess that a possible second "phase" of edits could be to "modernize" old articles.

I'm taking note of your ideas and I'll try to create some new pages today.

Concerning the addition of your channel: I tried to include as many YouTube channels I could find that were clearly displaying / playing around with Tidal. For now, I think that we can keep it here. If it makes you feel uncomfortable, I can also remove it.

1 Like

It's all good - you've put it there for a reason which makes sense (and I'm not uncomfortable, mostly flattered tbh)

For videos it would be nice to showcase a wide range of performances, and especially not include only videos by white men. We could maybe find something to show a randomly selected video.

1 Like

Ok, message received: new website.

  • now there are videos on the front page, &nbsp style. Looks ok though.
  • where to find samples: included my personal list of goto websites. Add your favorite websites.
  • reference section is there.
  • transitions + type signatures here and there.

I will try to focus on new contents from now on. There are some weakpoints in the doc: technical aspect, more creation-oriented tutorials (e.g. how to play piano with Tidal), and so on.

2 Likes

Is there currently a search function, or is that to be added later?

There isn't a search currently but I've applied to the Algolia docsearch service that would take care of this. I haven't heard back from them yet though.

Here's the info: Search | Docusaurus
Alternatively we could roll our own: Run your own | DocSearch

1 Like