These are really insightful comments, thanks!
Raholeun wrote: ↑Wed Aug 21, 2024 4:18 am
bradrn wrote: ↑Tue Aug 20, 2024 9:00 am
Just let me know when you can get around to it.
Please allow me to tackle this haphazardly. I started with the
Getting Started page.
‘A very good place to start’, as they say.
(By the way, I had some thoughts about how I could make the
Reference Guide clearer, so I’ll probably be doing some further restructuring on that in the next day or two. You can read it but probably best to wait until I’m done that.)
Occasionally, a sound change is followed by a commented section that illustrates how a specific item is impacted by the change. This is particularly helpful for those who are not yet familiar with the formulaic nature of sound change notation. Unfortunately, the use of examples is inconsistent. Sometimes, the input and output are provided within the code block, other times in the preceding or following text, and in some instances, no examples are given at all. It is recommended to adopt a consistent method for presenting examples. Ideally, an example should be included in the code block for every sound change demonstrated, regardless of how inane the result may appear.
Likewise, the guide sometimes provides counterexamples by stating "; no change in". This is useful and you might consider using them more often.
All good suggestions. I’ll add some more examples now.
Also, given that you use the angle brackets in passing, I’ve realised that I’m a bit inconsistent in when I use them. That’s something else to think about.
Building on the previous point, users might sometimes struggle to understand why their sound change isn’t functioning as expected or why it’s causing an error. ncluding a section in the documentation that offers troubleshooting tips or a 'debugging guide' would be highly valuable. This could cover common mistakes, how to identify where an issue might be occurring, and steps to resolve typical errors. I guess it is preferable to empower users to diagnose and fix their issues on their own, rather than having to post here (or worse, DM you) and take up your time.
Debugging is… tricky. At the moment, it’s mostly a matter of ‘stare at the sound change and hope’. Still, there’s a few tricks I’ve worked out, and it makes a lot of sense to document them.
(It will get a bit easier in the next version of Brassica, which will add an option to see intermediate stages.)
The relationship between wildcard tilde deletion and deletion via whitespace is not entirely clear to me. While the documentation introduces tilde deletion and explains the specific function it performs that whitespace deletion cannot, it doesn’t clarify whether tilde deletion can be universally applied in all scenarios where whitespace deletion is used. For example, you might want to explain why
is or is not equivalent to
Ah… interesting. To me, those things are so totally different I didn’t even realise they could be confused.
An attempt at an explanation:
- When the replacement of the rule is blank, that simply means ‘delete the whole target’, i.e. ‘replace the target with <blank>’.
- The tilde is more complicated: it means ‘skip over the next category in the target’, which in most cases results in deletion (unless one uses backreferences or similar). It doesn’t really make sense to say ʔ / ~, because there’s no target category to skip over. The tilde is meant for cases like, say, Rounded [a e i] / ~ [ɔ ø y], where the first category in the target corresponds to no output in the replacement.
Finally, in the section about the graphical interface it is stated: "The graphical interface appears as follows (on desktop)". To me it is unclear if this implies that the web version is lacking some features mentioned. If so, what are the differences? If the web and desktop version are functionally identical, that is good to state as well.
What I meant to say was, ‘the graphical interface looks like this on both desktop and web, so here’s a representative screenshot of the desktop version’. The two are generally identical: the main differences are that the web version doesn’t (yet) support MDF, and it’s a lot slower.