Add a NEST documentation style guide

[jessica-mitchell]

We've been discussing having a style guide for quite some time with the aim to help reduce inconsistencies in documentation writing.
This PR introduces a style guide inspired from several other style guides around the interwebs.

It includes several sections regarding English language as well as formatting and markup notation.

Please note:

There is a lot that still needs to be discussed here! @jougs @heplesser @terhorstd I'm sure you all have thoughts on this topic.

• Any information that is missing? Anything too excessive?

• Do we want to use an external style guide (like Microsoft's or Google's style guide) as a reference, in case people run into questions we do not address in our style guide?

• Some of the choices like formatting marks made here are based on what we do usually or what has been discussed, but obviously we can make changes as we see fit. We just need to make sure that readability is improved with the choices we make not impeded.

Thanks to @sarakonradi for contributing to this as well.

[heplesser]

@jessica-mitchell Thanks for all the fixes! But I still see no bullet points in the rendered lists. Looking at the HTML code reveals that the lists are properly encoded as lists, but with <ul class="simple"> and apparently

dl, ol, ul {
    margin: 0;
    padding: 0;
    list-style: none;
    list-style-image:none
}

in theme.css. I assume the zeros and nones here are the problem. It is the same with Safari and Firefox. Do you have any ideas?

[jessica-mitchell]

Points still in need of discussion:

• Should we say something about the use (or not) of contractions, e.g., "doesn't", "isn't", etc?
• A policy on punctuation of and around "eg" and "ie"?
• Conventions for reference labels (e.g., use sec_, fig_ eq_ at the beginning of each reference label to denote the type of reference)
• numerate equations and refer to them?
• Formatting: backticks, emphasis (bold, italic)
  • items which have markup with :role:`item`
    • glossary items
    • functions, classes etc.
    • documents, sections within documents
    • math equations
    • Sphinx has other possible roles
  • What formatting should the following items have?
    • in line code - dbl back tick
    • paths/filenames - dbl back tick
    • commands - dbl back tick
    • model names - dbl back tick
    • parameters
    • variables (x)
    • values
    • variables with assigned values (x = 1)
    • values with symbols ( 5 mV)
    • types (bool, int)
    • meta characters (backslashes)
    • special characters (ampersands, math symbols)
    • words we want emphasized in text - bold / italic?

[jougs]

@jessica-mitchell: would it be possible to post a link to a rendered version? Thanks!

[jessica-mitchell]

@jessica-mitchell: would it be possible to post a link to a rendered version? Thanks!

Yes, here you go: https://nest-test.readthedocs.io/en/nest_styleguide/contribute/styleguide/styleguide.html

[clinssen]

There are many links in the document to external resources, consider gathering all of them in the References section at the bottom of the document.

[jessica-mitchell]

@clinssen most of your suggestion I added (see exceptions in comments above), including references at the bottom of the page. Thanks!

[heplesser]

@jessica-mitchell Just a few more details ;).

[jessica-mitchell]

@heplesser I applied your suggestions, thanks!

[heplesser]

@jessica-mitchell Great work!

[heplesser]

@terhorstd @jougs You are either set up as reviewers or have commented earlier on the style guide. Do you still want to review/comment or can we go ahead and merge this one with two approvals in place?

[terhorstd]

Just two minor remarks. Since those are not critical we could also add them incrementally. Add them if possible.
👍

[jougs]

Beautiful! I have added some minor suggestions.