I know how to look up tidal-doc/off_en.md at main · tidalcycles/tidal-doc · GitHub but I really prefer to have docs as close to the actual source code as possible. From a user's standpoint, it allows :doc off (etc.) in a ghci session, and (maintainer's concern) code snippets in haddocks can (should) be extracted and evaluated for automated tests - to detect wrong code - and outdated documentation.
I think that the issues in the main repo are the best place for requesting code documentation or flagging incomplete/out of date docs.
In terms of contributing, what information for potential contributors would you like to see? Links to Haddock? Example syntax?
Somewhat as an aside, I definitely agree that we should keep putting more things in the Haddock documentation, ideally also compiling it into a reference that could live in tidal-doc.
what information for potential contributors would you like to see?
where is the primary place for documentation, what are secondary places (answers might be different for different types of docs)
how is duplication avoided between these places, or what degree of duplication is reasonable - but then what is the method to keep things in synch (with each other, and with the source code)
... more things in the Haddock documentation, ideally also compiling it into a reference that could live in tidal-doc
Well it already lives on hackage? E.g., Sound.Tidal.UI - that's the off function whose documentation I was missing. For many others, docs looks really nice, and are super useful, and hackage's build process ensures that names and types of functions are indeed correct.
I’ve long been a fan of single-sourcing documentation whenever possible, and as close to the source code as possible. Once Haskell became my day job, the combination of hoogle, hackage, and haddocks truly cemented that belief.
It’d be lovely if Tidal could over time evolve in the direction of deriving its web site documentation from the haddocks, as much as possible/practical.
Yes. I agree completely for code that I use and write for work (research, teaching). But - counter-arguments (against having haddocks as the only docs), in light of the diversity of the tidal community:
how do you do internationalisation with haddock? (For "hard" technical reference, English-only is fine. But tutorials, etc.)
how do you enable non-Haskellers to write docs? (they don't want to touch the source repo. But there could be a specific commit hook (or whatever) that checks that only haddocks (not code) was changed.)
I don't think it's a matter of having Haddocks as the only docs—it's just a matter of priority. As things currently stand, we prioritize having a separate docs website in part because of the counter-arguments you raise, and as a result, the original Haddock docs suffer (to your initial point).
My suggestion is to point out that the current docs website lacks a complete reference to the entire library. This has been requested, and I think the way to make it is by automatically generating Haddock docs and then transpiling that HTML into Markdown in the style of our docs website that gets dumped into a special folder in the docs repo. For a while this would be kind of a mess, because the Tidal api/Haddock docs are kind of a mess, but it would encourage us to fill out the docs, not export internal functions, etc.
On the counter-arguments:
Internationalization would work fine—the generated markdown docs get checked into tidalcycles/tidal-doc, and then could be manually copied into the corresponding translation branches of the docs repo. Updates wouldn't be translated, but that's already an issue with any of the docs (and thanks so much to anyone who is interested in translating things, or already has!)
The non-Haskellers issue worries me the most. What I'm proposing would only be a section within the docs website, so most of the tutorials and guides and introductory information would still be hand-written. I'm open to other opinions, but I think it would be okay to limit reference docs (ie, specific descriptions of individual functions or groups of functions) to Haskell contributors, as they're the most likely to accurately describe technical details.
Ideally, moving more of the docs directly into the repository might encourage more people to contribute to the repository, which would be a very good thing indeed! I've seen a bit of a bottleneck on contributions where things come in and kind of wait until @yaxu has time to make the final call on merging things, but I think that's mostly a matter of tradition, and if we sort out responsibilities a bit more, we could definitely have a few folks to guide non-Haskellers through the process of submitting Haddock pull requests.
100% agree from me re: the counter arguments and things like mindofmatthew’s suggestions too. Though there may still be some manual sync and update steps involved, I expect that Tidal can get to a point where everything has great docs, both on the haskell side and on the site, with regular contribution from both “sides” of that hazy line of user technicality.
That said, there’s not much else for me to add at the moment which has not already been put well by others.
I have some supporting remarks and an alternate view. But first -- is there an alternative to the term "non-Haskellers"? It feels just a little exclusive. Maybe "not-yet Haskellers"?
Disclosure: I'm relatively new to Tidal and have been contributing to the web site User docs, with 31 commits to GitHub - tidalcycles/tidal-doc So I have a bias.
I love the idea of a true Language Reference tied closely to the actual code (hopefully) written in a way that doesn't assume deep knowledge of Haskell. In my early learning stages, I was disappointed not to have this. If it were relatively easy to contribute, with a guide on how to, I would enjoy contributing, and I think others would as well.
I also feel that there will always be a place for a different style of documentation - and not just the installation, tutorial, configuration, meet the community, etc guides. Docs that focus on the live coding / musical experience. Or "what" a function does in a musical context - vs "how" it works from a code perspective. This kind of writing can encourage more narrative description and more robust examples that can sometimes be lacking in code documentation.
The current website documentation is organized in two parts:
Documentation (Intro to TIdal, Install, Text Editor, Config, Tutorial, etc)
Reference (Basic and Reference) with some concepts (what is a cycle) but mostly control and function descriptions with lots of short examples in code blocks.
What I would argue for is three sections:
How to Install and Use Tidal
User Guide (by functional grouping)
Language Reference (code docs)
I sense some pull in this thread to replace section 2 with an expanded and more complete section 3. To me, this poses a risk of loosing something valuable.
To illustrate what a good User Guide can contribute, see the current reference section on Sampling: https://tidalcycles.org/docs/reference/sampling
It groups together a series of functions relevant to manipulate samples and has a narrative about using them that I think is really helpful. It is something I would not expect in a Language Reference.
"Not-yet-Haskellers" to be sure! I think it's just a bit of self-consciousness about how nobody wants to learn our niche language, but I get how it can come across as elitist. As someone who learned Haskell by messing around with the Tidal library, it's a path I highly recommend!
This gets back to the initial post, and I'd be happy to start drafting an addition to CONTRIBUTING.md. Also, if we don't have a guide to contributors on the docs site, we definitely should. p5's documentation for contributors is very thorough, and a good reference point for things we could include.
This is a great structure, and I don't mean to suggest that 2 get replaced by 3. Ideally, there'd be a way to embed parts of 3 into 2 (like function signatures, deprecation notes, etc), so that docs can auto-update when functions change, but narrative descriptions of how a set of functions fit together or fit within a specific tradition of electronic music are super useful.