Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation restructure #151

Merged
merged 4 commits into from
Jul 11, 2023
Merged

Documentation restructure #151

merged 4 commits into from
Jul 11, 2023

Conversation

jfrost-mo
Copy link
Member

@jfrost-mo jfrost-mo commented Jul 10, 2023

The documentation has been reorganised to better allow distinct kinds of documentation, with distinct audiences, to be written.

This involves splitting the documentation into several distinct sections based on how it should be written. This is Tutorials, How-to guides, References, and Explanations.

  • Tutorials are for people learning their way around.
  • How-to guides answer the "how?".
  • References answer the "what?".
  • Explanations answer the "why?".

This is a commonly used, and well regarded documentations style used by projects such as NumPy.

More information can be found here: https://documentation.divio.com/

Fixes #146

The documentation has been reorganised to better allow distinct
kinds of documentation, with distinct audiences, to be written.

This involves splitting the documentation into several distinct
sections based on how it should be written. This is Tutorials,
How-to guides, References, and Explanations.

 * Tutorials are for people learning their way around.
 * How-to guides answer the "how?".
 * References answer the "what?".
 * Explanations answer the "why?".

This is a commonly used, and well regarded documentations style used
by projects such as NumPy.

More information can be found here: https://documentation.divio.com/
@jfrost-mo jfrost-mo added the documentation Improvements or additions to documentation label Jul 10, 2023
@jfrost-mo
Copy link
Member Author

This PR just restructures the documentation. It will be an ongoing effort to expand and update the documentation.

@github-actions
Copy link
Contributor

github-actions bot commented Jul 10, 2023

Coverage

@jfrost-mo
Copy link
Member Author

To aid review, here is a rendered version of the documentation.

@jfrost-mo jfrost-mo marked this pull request as ready for review July 10, 2023 09:29
@jfrost-mo jfrost-mo requested review from jwarner8 and removed request for Sylviabohnenstengel July 10, 2023 09:37
docs/source/index.rst Outdated Show resolved Hide resolved
@jfrost-mo
Copy link
Member Author

jfrost-mo commented Jul 11, 2023 via email

@jfrost-mo jfrost-mo requested a review from jwarner8 July 11, 2023 09:36
@jfrost-mo jfrost-mo merged commit 732d5e2 into main Jul 11, 2023
5 checks passed
@jfrost-mo jfrost-mo deleted the documentation-restructure branch July 11, 2023 09:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Do a readability pass of the documentation
2 participants