Time Nick Message 21:31 MTDiscord We need to clarify when and how to use each Admonition, I'm seeing a lot of jumps from just TIP to WARNING with no in between 21:36 MTDiscord I usually use "TIP: do the following" and "WARNING: don't do the following" 21:36 MTDiscord often the two are of course related, as in "WARNING: don't do this" and "TIP: use this workaround instead" 21:37 MTDiscord Using two for one statement is bad practice, it's extra visual noise and separates related statements. 21:54 MTDiscord I think CAUTION should typically be used for "don't do the following" and WARNING should be used for "do this and you will regret it" 21:54 MTDiscord To be more specific: asciidoc NOTE: This detail is noteworthy. TIP: This is useful. IMPORTANT: You should _really_ know this. CAUTION: If you're not careful, there may be consequence. WARNING: If you do X, Y will happen. 21:55 MTDiscord If you use WARNING all the time then it will lose its power to communicate something of great importance. 21:55 MTDiscord The difference between CAUTION and WARNING isn't always intuitive, Asciidoctor actually links a whole article on the subject: https://www.differencebetween.com/difference-between-caution-and-vs-warning/ 21:57 MTDiscord Basically, Caution is used when the reader should take care before proceeding, while Warning is used when the reader shouldn't proceed at all. 21:58 MTDiscord WARNING: Don't touch this, you'll die. CAUTION: This knife is very sharp, you could cut yourself if not careful. 22:24 MTDiscord Also, did we all agree that breaking on sentences was our official style? 22:25 MTDiscord What? 22:25 MTDiscord I dont think that was ever discussed 22:25 MTDiscord https://discord.com/channels/369122544273588224/926231483155378176/926938178391265301 22:26 MTDiscord The short answer is no, it was just noted by Josiah and myself 22:26 MTDiscord Ah, so break internally, which will still show up as normal in render 22:26 MTDiscord yeah 22:26 MTDiscord Im fine with that 22:48 MTDiscord I'd like to add some general format rules to HOWTO, this is what I have so far: asciidoc * Use one sentence per line * Define macros for long URLs, or those used multiple times * Use delimitated example blocks for examples, but not for general function usage 22:52 MTDiscord (These are more noteworthy rules than an exhaustive list)