documentation

[alexsquires]

I've added a documentation section with a focus on writing as opposed to reading. I thought this would be a doss, but turns out it's hard. Happy to be beaten over the head with the opinions of others.

[arm61]

Thoughts:

• Change title to "Writing documentation", then More-on-Documentation #64 will precede this section as it is explaining how to find and read documentation.
• Add "reading and finding documentation" to prerequisites
• Maybe don't contextualise the first paragraph in "research", perhaps "learning and research" (keep the audience open as possible)
• 'functional' to functional (formating IDGAF really)
• Make 'the code below solves Bragg's law for an orthorombic crystal to determine the Bragg angle associated with a given miller plane' bold
• make the # symbol code case
• # define miller indicies to # define miller indices
• Are you wanting comments and docstrings to be two separate sections?
• "emphasis" to "emphasise"
• "arguemnts" to "arguments"

I like this

[alexsquires]

• Are you wanting comments and docstrings to be two separate sections?

My thinking here was that docstrings require an appreciation of functions, but I don't feel like an understanding of basic documentation should necessitate understanding functions, so I separated them out. I'm not strongly attached to this way of working though.

[arm61]

I personally would be happy with them together, just change the name of that subsection to "Docstrings" or something and add functions to the overall prerequisites (this part will definitely be coming after the functions part in the structure of the book so it should be fine).

[arm61]

Happy for you to merge this @alexsquires