decide on spoilers policy

[kbinreallife]

description

come to decision on how spoilers are presented on wiki

docs?

• [x] decision document (comments in issue)
  • are they obscured? in what style are they obscured?
• [x] put decisions in style guide

how to validate?

decision is made and 5 people have had until 3 days to review proposed and decision doc

what work do we need to do to notify people about this work being completed?

announce start and end in project post

[danswann]

Proposed Spoiler Policy for wiki_v1

This is a proposal for a policy to handle spoiler content on the wiki. It includes suggestions for how to define what is and is not a spoiler, and how to display spoilers on a wiki page.

The purpose of this policy is to establish a baseline. Once created, it should be a living document updated as necessary when concerns arise.

Please offer feedback on both the goals and the design decisions to improve this policy.

Goals

This spoiler policy defines several goals, that any design decision should work to fulfill:

1. Users who go to the wiki looking for spoilers should be able to find them.
2. Users should be able to access spoiler content easily, with minimal interaction overhead.
3. Users who go to the wiki and do not want to be handed the answers should feel safe that they will not accidentally spoil themselves.
4. Article writers should have a good baseline idea of what is and is not a "spoiler."

Design Decisions

Here are several design decisions, and which goals they support, separated into decisions that dictate either style or content.

Style/Layout

These are suggestions for how spoilers should be displayed.

1. Spoilers should exist somewhere on the same page as the relevant content. (Goal 1, 2)
2. When practical, spoilers should be hidden by default. (Goal 3)
3. When possible, spoilers should be grouped together into a single section per page/topic. We should not use inline spoiler obfuscation that occurs in random short chunks throughout a page. They should instead exist in their own, collapsible section. (Goal 2)
4. In cases where the vast majority of the content on a given page would be considered spoilers, and it would be silly to obscure most of the page, it is instead sufficient to put an overt message warning the reader of that fact. This warning should exist either at the top of the page or immediately after a small introductory section that itself is free of spoilers. (Goal 1, 2, 3)

Content

These are suggestions for how spoilers should be defined.

Upgrades

1. Any feature of a lock that can be discovered by providing incorrect arguments is not a spoiler. For example, given the following: the fact that ez_21 takes a string which is some kind of unlock command, and that c003 takes a string which is the name of a color, do not need to be obscured. (Goal 4)
2. Explicit complete answers to locks are spoilers. The complete list of unlock commands, and the complete list of colors would be spoilers. Where many solutions exist, using one answer as an example should be fine, e.g. c001:"blue" in an example invocation of c001 or a single magnara solution. (Goal 4)

   Lore Stuff

3. For quests/events that are still playable, the entry point should not be considered a spoiler, and should be clearly separated from any further exploration of the script(s). Pretty much everything else is a spoiler, as it depends on the user having figured out the correct arguments to pass to proceed past the entry point.
4. A short summary of a character should not be considered a spoiler. Details about the character that are only revealed by having progressed through some event or other puzzle are spoilers.

Since from either a lore perspective (character/event/etc. pages) or from a puzzling perspective (quest/event/etc. pages) these will probably be majority spoilers, the spoiler warning described above in the Style/Layout section should be used, rather than hiding the majority of the page.

Scripting Stuff

Generally not applicable. If there are spoiler concerns in documentation or guides, they can be handled on a case-by-case basis, and the spoiler policy can be updated if necessary to address those concerns going forward.

Examples

This is an example of an expandable spoiler section, which would be collapsed by default.

This is an example of a "spoilers ahead" warning.

NB: these images are just to demonstrate the concepts discussed. The spoiler policy does not dictate things like what colors should be used, what sections should be named, etc.

Limitations

For both locks and lore, there is some grey area in between the definitions of what is never a spoiler and the definition of what is always a spoiler, especially for more complicated puzzling at higher tiers. I think trying to come up with a definition that is perfectly applicable to all content is either very difficult or impossible, and that instead the living document status of the policy will allow us to update it to account for novel issues.

[matr1x-hackmud]

My only concern with the "spoilers ahead" warning style is that I'm unsure of its efficacy for especially short articles, or when it shows up very early on in a longer article. My fear is that it might draw attention to the content because it is large, and someone's screen might be too physically large to obscure what lies below.

The Dwarf Fortress wiki gets around this by filling particularly spoilerific pages (https://dwarffortresswiki.org/index.php/DF2014:Underworld) with tons of newlines, but that seems very messy.

[danswann]

My only concern with the "spoilers ahead" warning style is that I'm unsure of its efficacy for especially short articles, or when it shows up very early on in a longer article. My fear is that it might draw attention to the content because it is large, and someone's screen might be too physically large to obscure what lies below.

Yeah, I thought about that too, but couldn't come up with anything better. I do not think massive blank space is the correct answer.

If the article is short enough that as much spoiler content fits on a page as non-spoiler content, then you'd probably use the collapsible anyway, rather than the warning. The example picture is short because it's contrived, not because I think it represents an appropriate size page or proportion of content for the warning in practice. Even on longer articles though, there's only so much we can do to cater to an individual viewport. At some point we will have to trust the user to manage their own eyeballs.

@matr1x-hackmud Do you think that it would be better to always use a collapsible spoiler block, even in something like an event page where the overwhelming majority of the content would be inside of it? I suggested that it might get silly visually, but honestly I'm not strictly opposed to trying it out. It may end up being the best compromise.

[matr1x-hackmud]

The example picture is short because it's contrived, not because I think it represents an appropriate size page or proportion of content for the warning in practice

That's fair. It will probably look fine when each page is appropriately fleshed-out.

@matr1x-hackmud Do you think that it would be better to always use a collapsible spoiler block, even in something like an event page where the overwhelming majority of the content would be inside of it? I suggested that it might get silly visually, but honestly I'm not strictly opposed to trying it out.

I really like the big banner for pages about content that's an outright walking spoiler. Lots of characters will probably need that, as will stuff like gibson (where theres maybe 1 or 2 outputs to talk about before we're in spoiler-land). I don't think the collapsible should be the only way we mark it.

An alternative is maybe having a third click-through to reveal an entire page, which might be an appropriate compromise without the styling implications of the collapsible (like the indentation and different background), but idk how easy that is to do in Docusaurus, whether it'd "force" JS on a reader, or if it's worth our time at this stage of the project.

[danswann]

without the styling implications of the collapsible (like the indentation and different background)

Yeah, tbh I'm fine with all spoiler content having similar formatting to non-spoiler content. That's more style guide territory. The only thing dictated by the policy would be that it is able to be hidden/revealed, and that it is hidden by default. The blue, indented box, just happens to be the default way Docusaurus renders <details> HTML tags.

idk how easy that is to do in Docusaurus, whether it'd "force" JS on a reader, or if it's worth our time at this stage of the project

Ease of implementation isn't too much of an issue here, it would be trivial to implement, especially since we have lead time from other blocking issues. I used the <details> HTML tag in this example because you had expressed concerns earlier about using JS, and that's the only non-JS way to hide things that I am personally familiar with without further research.

[matr1x-hackmud]

If it's just a matter of making different <details> styling classes, then sure. Count me on board with your draft!

[ghambhackmud]

Lots of characters will probably need that,

I think there's still enough room on the character pages to give brief summaries of the characters, like descriptions, without being out right spoilery.

the big banner for pages about content that's an outright walking spoiler

Is it possible to have a large banner that inherently has too many new lines and being able to click it to collapse and continue on?

[danswann]

Is it possible to have a large banner that inherently has too many new lines and being able to click it to collapse and continue on?

Possible, sure, but is pushing the content you don't want people to see out of the initial viewport functionally different from just hiding the content you don't want people to see inside a spoiler block?

[ghambhackmud]

Possible, sure, but is pushing the content you don't want people to see out of the initial viewport functionally different from just hiding the content you don't want people to see inside a spoiler block?

No, I don't think so but I was just trying to add options to the banner warning style, especially in regards to

I really like the big banner for pages about content that's an outright walking spoiler. Lots of characters will probably need that, as will stuff like gibson (where theres maybe 1 or 2 outputs to talk about before we're in spoiler-land). I don't think the collapsible should be the only way we mark it.

Though I don't think we'd actually have too much content that is mostly empty with no spoilers shown.

[tukib]

Awesome spoiler policy, on board as well.

An alternative is maybe having a third click-through to reveal an entire page, which might be an appropriate compromise without the styling implications of the collapsible (like the indentation and different background), but idk how easy that is to do in Docusaurus, whether it'd "force" JS on a reader, or if it's worth our time at this stage of the project.

I do not know the limitations of Docusaurus, but having a button to reveal subsequent page content is possible with just a checkbox and some CSS work. See MDN Docs for :checked (2nd example is relevant) and the Subsequent-sibling combinator. There may also be ways to automatically select every appropriate element below the warning too. I may be able to cook up a draft PR later for that to save others' time.

[ghambhackmud]

We're going to run with Daniel's proposal for now. He's making a PR to address this and we are shoving it in the readme.md.