docs: add contributing style guide for docs

[lostmygithubaccount]

Please describe the issue

we should add a style guide (and perhaps general guide) for contributing to documentation

if you have strong opinions on style or anything, feel free to weigh in here

Code of Conduct

• I agree to follow this project's Code of Conduct

[cpcloud]

Some of my opinions:

• wrap long prose strings (somewhere between 80-90 characters, vim's default wrapping seems fine)
• any computations that can't or shouldn't be done again should use freeze: auto in the YAML front matter, and never freeze: true. freeze: true results in silently stale pages. freeze: auto will cause CI to fail if computations occur because a page has not been frozen locally and pushed to a PR.
• format code blocks with black or as close as possible to it
• freeze: auto should always be used per page unless there's a good reason to use it for a collection of pages (blog posts, for example)
• prefer <language> instead of {.<language>} in triple-backtick-quoted code text

so instead of

```{.python}
# code
```

we do

```python
# code
```

[gforsyth]

As per #6957 with an overwhelming 5 votes cast, always refer to the library name as Ibis in prose.

[gforsyth]

wrap long prose strings (somewhere between 80-90 characters, vim's default wrapping seems fine)

Very strong agree on this. It makes diffs on prose and reviewing prose MUCH cleaner

[gforsyth]

Other opinions:

• No jupyter notebooks (in ipynb form) allowed -- they can be used to author something but only the converted qmd file should be committed.
• Avoid the passive voice. Either Ibis does something or the user does something (or a particular backend does something). Hot take: if the passive voice seems like the best way to describe something, we probably need to redesign the API / code in question, because it is clearly riddled with side-effects.
• Try to avoid using simply / simple, obviously, just, when describing things that Ibis makes easier. Either the simplicity is self-evident or it isn't.
• LLMs do not write well, they write correctly, but it's doggerel. (this one probably doesn't belong in the style guide)

[lostmygithubaccount]

Try to avoid using simply / simple, obviously, just, when describing things that Ibis makes easier. Either the simplicity is self-evident or it isn't.

huge +1, I am personally very bad at this (and similar words), please do call it out!

wrap long prose strings (somewhere between 80-90 characters, vim's default wrapping seems fine)

I'm actually against this...unless this is something a formatter handles? otherwise I find this makes it very hard to edit (dealing w/ where to place newlines)

[cpcloud]

I'm actually against this...unless this is something a formatter handles? otherwise I find this makes it very hard to edit (dealing w/ where to place newlines)

Can you elaborate a bit? Most editors have "hard wrap" functionality that should handle this.

[cpcloud]

Standard markdown doesn't render single linebreaks, while GitHub Flavored Markdown does. Perhaps that is confusing the issue?

[lostmygithubaccount]

I use vim/nvim and it does wrap lines for me, but doesn't insert linebreaks. if this is a case of my just doing something wrong then I'm happy to conform

[gforsyth]

I use vim/nvim and it does wrap lines for me, but doesn't insert linebreaks. if this is a case of my just doing something wrong then I'm happy to conform

You can use gq and then a movement to wrap. gqG will linewrap the whole document.

[cpcloud]

I believe you have to use gw in recent versions of neovim 😬

[gforsyth]

that seems like a weird choice, but ok!