From d21bc27da2807c67ebdbfb4d44b458a42cd77a71 Mon Sep 17 00:00:00 2001 From: "E. G. Patrick Bos" Date: Wed, 25 Sep 2024 16:19:37 +0200 Subject: [PATCH 1/4] reorganize chapters: add technology guides section Also moved language guides to the root folder level, because I find it annoying to have to click into the best_practices folder. Note: datasets still has to be moved to technologies, but there is an outstanding PR on that and I don't want to stress git's ability to detect moved files too much, otherwise we lose the ability to easily browse edit history. --- _sidebar.md | 22 ++++++++++--------- .../bash.md | 0 .../ccpp.md | 0 .../fortran.md | 0 .../javascript.md | 0 .../languages_overview.md | 0 .../python.md | 0 .../language_guides => language_guides}/r.md | 0 .../opencl_cuda.md => technology/gpu.md | 0 technology/technology_overview.md | 7 ++++++ .../user_experience.md | 0 11 files changed, 19 insertions(+), 10 deletions(-) rename {best_practices/language_guides => language_guides}/bash.md (100%) rename {best_practices/language_guides => language_guides}/ccpp.md (100%) rename {best_practices/language_guides => language_guides}/fortran.md (100%) rename {best_practices/language_guides => language_guides}/javascript.md (100%) rename {best_practices/language_guides => language_guides}/languages_overview.md (100%) rename {best_practices/language_guides => language_guides}/python.md (100%) rename {best_practices/language_guides => language_guides}/r.md (100%) rename best_practices/language_guides/opencl_cuda.md => technology/gpu.md (100%) create mode 100644 technology/technology_overview.md rename {best_practices => technology}/user_experience.md (100%) diff --git a/_sidebar.md b/_sidebar.md index df0e2c25..95ea44b1 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -6,14 +6,16 @@ * [Releases](/best_practices/releases.md) * [Documentation](/best_practices/documentation.md) * [Standards](/best_practices/standards.md) - * [UX - User Experience](/best_practices/user_experience.md) - * [Datasets](/best_practices/datasets.md) - * [Language Guides](/best_practices/language_guides/languages_overview.md) - * [Bash](/best_practices/language_guides/bash.md) - * [JavaScript and TypeScript](/best_practices/language_guides/javascript.md) - * [Python](/best_practices/language_guides/python.md) - * [GPU](/best_practices/language_guides/opencl_cuda.md) - * [R](/best_practices/language_guides/r.md) - * [C and C++](/best_practices/language_guides/ccpp.md) - * [Fortran](/best_practices/language_guides/fortran.md) + * [Datasets](/best_practices/datasets.md) +* [Language Guides](/language_guides/languages_overview.md) + * [Bash](/language_guides/bash.md) + * [JavaScript and TypeScript](/language_guides/javascript.md) + * [Python](/language_guides/python.md) + * [R](/language_guides/r.md) + * [C and C++](/language_guides/ccpp.md) + * [Fortran](/language_guides/fortran.md) +* [Technology Guides](/technology/technology_overview.md) + * [GPU programming](/technology/gpu.md) + * [UX - User Experience](/technology/user_experience.md) + * [Contributing to this Guide](/CONTRIBUTING.md) diff --git a/best_practices/language_guides/bash.md b/language_guides/bash.md similarity index 100% rename from best_practices/language_guides/bash.md rename to language_guides/bash.md diff --git a/best_practices/language_guides/ccpp.md b/language_guides/ccpp.md similarity index 100% rename from best_practices/language_guides/ccpp.md rename to language_guides/ccpp.md diff --git a/best_practices/language_guides/fortran.md b/language_guides/fortran.md similarity index 100% rename from best_practices/language_guides/fortran.md rename to language_guides/fortran.md diff --git a/best_practices/language_guides/javascript.md b/language_guides/javascript.md similarity index 100% rename from best_practices/language_guides/javascript.md rename to language_guides/javascript.md diff --git a/best_practices/language_guides/languages_overview.md b/language_guides/languages_overview.md similarity index 100% rename from best_practices/language_guides/languages_overview.md rename to language_guides/languages_overview.md diff --git a/best_practices/language_guides/python.md b/language_guides/python.md similarity index 100% rename from best_practices/language_guides/python.md rename to language_guides/python.md diff --git a/best_practices/language_guides/r.md b/language_guides/r.md similarity index 100% rename from best_practices/language_guides/r.md rename to language_guides/r.md diff --git a/best_practices/language_guides/opencl_cuda.md b/technology/gpu.md similarity index 100% rename from best_practices/language_guides/opencl_cuda.md rename to technology/gpu.md diff --git a/technology/technology_overview.md b/technology/technology_overview.md new file mode 100644 index 00000000..36dcbea0 --- /dev/null +++ b/technology/technology_overview.md @@ -0,0 +1,7 @@ +*Page maintainer: Patrick Bos* [@egpbos](https://github.com/egpbos) + +These chapters are based on our experiences with using specific software technologies. + +The main audience is RSEs familiar with basic computing and programming concepts. + +The purpose of these chapters is for someone unfamiliar with the specific technology to get a quick overview of the most important concepts, practices and tools, without going into too much detail (we provide links to further reading material for more). \ No newline at end of file diff --git a/best_practices/user_experience.md b/technology/user_experience.md similarity index 100% rename from best_practices/user_experience.md rename to technology/user_experience.md From 13c7624f52823dd098acc916c108560ecbe4bc0c Mon Sep 17 00:00:00 2001 From: "E. G. Patrick Bos" Date: Thu, 26 Sep 2024 20:31:30 +0200 Subject: [PATCH 2/4] update README: add technology guides --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d2f7a557..b8b17a17 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,12 @@ If you are looking for an overall picture of best practices, read [The Turing Way](https://the-turing-way.netlify.app/index.html) first. We joined forces with that guide for most of our generic research software engineering advice. -Because The Turing Way is language agnostic, this guide mostly provides +Because The Turing Way is programming language agnostic, this guide provides addtional specific -[language guides](best_practices/language_guides/languages_overview.md). -*Please be aware that most remaining language agnostic content is outdated, +[language guides](language_guides/languages_overview.md). +We also provide [technology guides](technology/technology_overview.md) on digital technologies we use often in our projects with research partners. +*Please be aware that most remaining "best practices" content is unmaintained, be careful when using it.* -We plan on removing that content (#286). +We plan on removing that content ([#286](https://github.com/NLeSC/guide/issues/286)). If you would like to contribute to this book see [CONTRIBUTING.md](CONTRIBUTING.md). From 3157686cdb875537eae779a3f95712953d765dc7 Mon Sep 17 00:00:00 2001 From: "E. G. Patrick Bos" Date: Fri, 27 Sep 2024 21:46:54 +0200 Subject: [PATCH 3/4] move datasets chapter to technology as well --- _sidebar.md | 3 +-- {best_practices => technology}/datasets.md | 0 2 files changed, 1 insertion(+), 2 deletions(-) rename {best_practices => technology}/datasets.md (100%) diff --git a/_sidebar.md b/_sidebar.md index 95ea44b1..300268fa 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -6,7 +6,6 @@ * [Releases](/best_practices/releases.md) * [Documentation](/best_practices/documentation.md) * [Standards](/best_practices/standards.md) - * [Datasets](/best_practices/datasets.md) * [Language Guides](/language_guides/languages_overview.md) * [Bash](/language_guides/bash.md) * [JavaScript and TypeScript](/language_guides/javascript.md) @@ -17,5 +16,5 @@ * [Technology Guides](/technology/technology_overview.md) * [GPU programming](/technology/gpu.md) * [UX - User Experience](/technology/user_experience.md) - + * [Datasets](/technology/datasets.md) * [Contributing to this Guide](/CONTRIBUTING.md) diff --git a/best_practices/datasets.md b/technology/datasets.md similarity index 100% rename from best_practices/datasets.md rename to technology/datasets.md From 9161825b8a4c8cc3e6b3db530fdee71988cd3faa Mon Sep 17 00:00:00 2001 From: "E. G. Patrick Bos" Date: Fri, 27 Sep 2024 21:52:50 +0200 Subject: [PATCH 4/4] move best practices down in the menu --- README.md | 2 +- _sidebar.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b8b17a17..c686d857 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Because The Turing Way is programming language agnostic, this guide provides addtional specific [language guides](language_guides/languages_overview.md). We also provide [technology guides](technology/technology_overview.md) on digital technologies we use often in our projects with research partners. -*Please be aware that most remaining "best practices" content is unmaintained, +*Please be aware that most remaining [best practices](/best_practices/overview.md) content is unmaintained, be careful when using it.* We plan on removing that content ([#286](https://github.com/NLeSC/guide/issues/286)). diff --git a/_sidebar.md b/_sidebar.md index 300268fa..a9d8ca80 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -1,11 +1,5 @@ * [Introduction](/README.md) -* [Best practices](/best_practices/overview.md) - * [Code Quality](/best_practices/code_quality.md) - * [Code Review](/best_practices/code_review.md) - * [Releases](/best_practices/releases.md) - * [Documentation](/best_practices/documentation.md) - * [Standards](/best_practices/standards.md) * [Language Guides](/language_guides/languages_overview.md) * [Bash](/language_guides/bash.md) * [JavaScript and TypeScript](/language_guides/javascript.md) @@ -17,4 +11,10 @@ * [GPU programming](/technology/gpu.md) * [UX - User Experience](/technology/user_experience.md) * [Datasets](/technology/datasets.md) +* [Best practices](/best_practices/overview.md) + * [Code Quality](/best_practices/code_quality.md) + * [Code Review](/best_practices/code_review.md) + * [Releases](/best_practices/releases.md) + * [Documentation](/best_practices/documentation.md) + * [Standards](/best_practices/standards.md) * [Contributing to this Guide](/CONTRIBUTING.md)