Wow, another estival update! Still got plenty of those until the end of the month.

Docs and Tutorials

Documentation is always a big subject in open-source projects, and according to feedback, Castagne’s docs is one of the best, really complete for a project at this stage, and very lacking and obtuse. What gives?

The reality is that, not everybody needs the same docs, and thus they will have very different experiences of it. People that think Castagne’s doc is great is mostly technical people: Castagne functions are all explained, and most of the internal states in CASP have documentation, meaning you don’t need to experiment to understand Castagne. On the other end, someone not as technical will be lost more easily, as the getting started part of the docs is fairly minimal and split. Furthermore, small syntax drift makes docs not always up to date. Let’s talk about how I intend on taking these challenges!

First off, it’s good to know what kind of docs are present in Castagne and what they are needed for and their specific challenges. It’s a complex environment, so this multimodality reflects that.

• First off is the function reference, which is how to use each function provided. This is what most programmers mean when they say docs, as its the actual core of them.
• Then, specific to Castagne is CASP docs. All the gameplay is written in CASP, including stuff like walking or hitstun, and all of that is contained in CASP files and therefore outside of usual doc pathways.
• Module Docs is all the other parts of modules, describing how they work, what variables are available and what they do, etc.
• Text Docs, standalone pages. There’s a few of them covering parts of the engine such as the main loop or the language specification.
• Text Tutorials, which is exactly what it says, more oriented towards technical users.
• Video Tutorials, which cover some basics as well as some of the asset workflows as they go beyond the software. These are oriented towards less technical users. These are also the most annoying to update.
• In-Engine Tutorials, which guide you step by step in the engine.
• Example Characters, which show how its done and allow illustration of the concepts.

Access to the tutorials is currently done either from the website (which easily drifts away) and from the engine (which has a janky interface). Drift from reality is a concern, with in-engine tutorials being the easiest to keep in sync since they can be tested, and video being the hardest as they can’t and remaking them is a chore. Keeping docs up to date is a huge issue in programming and takes a lot of time, so it needs to be properly supported in the dev workflow.

That’s why docs have been a concern of the new version from the start. The best way to have docs up to date, is to make it easy to keep them so. As such, here’s a few of the key ways this happens:

• Stronger Release Script: Castagne’s release flow has a few manual steps, this is about removing some of them from that whole thing. Specifically, automating the docs rebuilding and upload, as well as making the tests automatic (I currently manually test that all the in-engine tutorials are working before each release). I’ll also add fetching from CASP files to have the state docs in the docs too.
• In-Engine Tutorial Focus: Tutorials are very finnicky, small changes can one-shot non-technical beginners even though all the logic is still there. It’s also the one that needs more entry points and polish. That’s why I want to make in-engine tutorials the central point: their programmatic nature makes them much easier to test against interface drift, they are the only mandatory access point (can’t guarantee you’ll go on the website) and they can be interactive to make information stronger to retain. This nature also means they can be automatically converted to text tutorials easily, and video tutorials albeit with some caveats. Being able to put the full focus on them will allow more coherence and going further, but it loses targetting of audiences through the medium, although other additional solutions can mitigate that issue.
• Testing: Already mentioned before, but the only way to ensure such a big amount of documentation in a complex software stays up to date is automatic tests. Testing the in-engine tutorials is already one thing I mentioned twice, but another idea (stolen from rust) is automatic testing of the functions themselves through examples. Every function will now have an example code with it (if applicable) that will be tested before release. That is quite an increase in workflow, but I’m already doing that one internally.

This should already fix a lot of the issues, and allows the standalong pages to focus on parts that don’t move much, such as the language specification or engine loop. But this would only improve the content of the docs, which is just one part. The second part is access, and that is just as important for a good tool. So, here’s the way you can access the docs:

• In-Engine: The docs already are accessible there, but they are not really usable. Improving their display, as well as making them an actual system that other tools can reference will help tremendously.
• Web: Already there, but having them as a separate website that is updated automatically will make them much stronger to read through. Having them start from the engine first will also allow different presentation online.
• Tooltips: Already exists, but expanding on having the docs always visible is a big concern. Function names appear faster, and how to use a function or CASP state is meant to be always close at hand.
• Help Me! Button: If you have a keen eye, you might have noticed the “Help Me!” button at the top of the interface. This is an additional system based on the tutorials that focuses on practical docs, namely to answer quick questions such as how to do armored moves. Compared to the tutorials, this is more of a cliff notes version, with usable snippets: the system can actually put some common blocks inside of your code! This also has a link to the community with guidelines so that we don’t have to say as often to people to include details.
• Programmatically: Not a priority at the moment, but you will be able to access the Castagne docs from an API. This will make it possible to create integrations such as bots and the like.

As you can imagine, that’s a huge amount of docs to make, and they won’t come in all at once. There’s also still an issue of what should the docs cover, and while I’ll talk more about this in the beginner estival post, at some point you stop being just technical and start going into the more artistic side. Some people have asked questions such as “how to make a move feel good?” and my answer of “add forward momentum to make it feel more powerful” tends to lead to mashslop games and is thus not universal. This is just one of the issues that can rise from the mission of the official tutorials, along with coverage / speed. That’s why in a second phase, a strong focus is going to be put in community tutorials, where you can interface with those tutorials system easily, and be referenced in various ways by the official software. As such, you can now explain to people how your custom proration algorithm works and why it’s good!

There’s other concerns, such as translation of said docs (can you feel the pain already?), but they are not as critical in this stage of the project. There’s also a bit of question over LLMs, which while I don’t like them or intend to shove them in the software for no reason, are often used by people instead of searching or asking, and their use in programming is more widespread than in art. They’ve already scrapped the Castagne docs and can produce CASP code from the tests I’ve done, and the programmatic interface could help local models be aware of what’s going on and thus reduce slop questions. I’m personally not convinced of their use here since Castagne is quite simple in practice, and I think the tutorial will be enough to put users in conscious control which will work faster, but hey if they are already taking my bandwidth they might as well be useful. I’ll take this time to note that I’m refusing the use of AI to write the docs, even though it’s a common use these days, as I want the docs to be quality and accurate. I’ve also got plans in the further future to make smaller vids myself and dev interviews, a bit outside of the general tutorials to make the results more complete.

Finally, a point I’m not going to expand on this time is the example characters. That’s because there’s a lot to say about them, especially at a beginner level, and how they tie into the engine itself. I think the ideas that were tied to them were good, but the execution could be better, which some of the new systems will definitely help with. An early note I’ll do is that there’s going to be several characters, and that they will be integrated into the tutorials both as characters and as examples.

As you can see, there’s a lot to say on docs, and it’s probably more complex than you’ve expected! And I’ve not even covered everything. In truth, such systems are central to software, and Castagne being complex AND a beginner-magnet, its docs need to grow in a way to support that. What would you make tutorials on? Next time, we’ll talk about beginners.