Isn't there an actual FAQ for the board software?

Discourse Feedback
1

When I went to FAQ - Discussions on Python.org , I expected to see something that would document e.g. the specific flavour of Markdown used for posts here, an explanation of the Discourse “tag” system etc. But instead, it shows me the Code of Conduct. As important as that may be, that doesn’t remotely resemble what I’d normally consider a “frequently asked question”, nor the answer thereto.

Does such a document actually exist? Where is it?

(And if not: how do I create those neat footnote thingies?)

2 Likes
2

For that bit, the answer is that you put [^1] where you want the footnote to appear, and somewhere else you write the text of the footnote as a paragraph starting with [^1]:. You can use numbers 2, 3, … for multiple footnotes. I don’t think they even have to be numbers, words will do as well.

For the rest, I don’t know I’m afraid, although I agree it would be nice to have it somewhere easily accessible from here.

3

I found the following summary of the syntax that Discourse (apparently) supports: https://markdown-it.github.io/

I also discovered that you can put footnote text inline with the syntax ^[put the text here][1]

  1. like this! ↩︎

1 Like
5

There are a series of interactive tutorials users have the option to complete via DMs with the bot here, that teach most of the basic and intermediate concepts. The meta.discourse.org site has a bunch of information, such as e.g. the Discourse New User Guide. And its own FAQ offers more high-level advice, something closer to what ours probably should.

I definitely agree we should change this, along the lines of the proposals iterated on the ChatGPT thread, e.g. @Quercus 's. It doesn’t seem to make any sense to have the entire content of the “FAQ” be just a copy/paste of the PSF CoC, which could instead be prominently linked at the top and in a FAQ answer. It just seems like there hasn’t yet been enough critical mass of consensus to take action on it yet.

TIL; I didn’t know (or maybe I forgot) that syntax was supported and thought only worked with the inline syntax instead, since the inline form is actually what is displayed to users. [1]

Ideally, Discourse would display these as normal footnotes, and inline Markdown footnotes as the current inline footnotes, to match the syntax to the visual presentation—it’s rather strange to use the “numbered” syntax for inline footnotes, and vice versa. This is something you brought up before, among other issues with the current inline-only footnotes, and in hindsight (despite arguing otherwise at the time) I think you’re right—though the presentation matching the syntax would really be the best of both worlds.

  1. And indeed, it seems it does. ↩︎

1 Like
6

Missing :.

Testing[^1]

[^1]: This works

Renders to:

Testing[1]

  1. This works ↩︎

4 Likes
7

I think that a FAQ for the board software (or a ‘user guide’, maybe) would be very useful.

I’ve discovered this, for example, which may be news to some, if not for all:

for a in range(10):
  print(b)

For the above code…

-print(b)
+print(a)

… which is:

```diff
-print(b)
+print(a)
```
1 Like