From d455d7b684c2fe2a0c600fd751d52e5cd9c1fbd0 Mon Sep 17 00:00:00 2001 From: Matthew Bourque Date: Wed, 25 Sep 2024 14:24:55 -0600 Subject: [PATCH 1/2] Moved purpose, motivation, scope to homepage of RtD --- README.md | 45 +++-------------------------------------- docs/source/index.rst | 47 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 026060b..1cd5999 100644 --- a/README.md +++ b/README.md @@ -1,51 +1,12 @@ # developer-guide -This repository provides guidelines for software developers at LASP. You can view the developer guide here: http://lasp-developer-guide.readthedocs.io/ - -## Purpose - -The purpose of this repository is to provide a collection of documented guidelines for software development workflows -and processes commonly used within Data Systems in order to assist developers in accomplishing their work. The developer -guide is managed within this version-controlled GitHub repository as to allow for the collaborative creation and -maintenance of the guidelines. - -## Motivation - -The motivation for this effort is two-fold: - - We are motivated by [Goal 3.1](https://confluence.lasp.colorado.edu/display/DS/2024-2027+Data+Systems+Strategic+Plan#id-20242027DataSystemsStrategicPlan-goal3) -from the 2024-2027 Data Systems Strategic Plan, which states "Create a set of living DS best practices and training -guides that include standard processes and expectations for common tasks". - - With the push towards open science and access (see [NASA’s directive SPD-41a](https://science.nasa.gov/researchers/open-science/science-information-policy/)) -we hope to also embody this openness in our internal processes. - -Historically, such documentation has been spread over multiple pages and spaces within confluence and specific projects. -The developer guide endeavors to bring these resources together in one centralized space, allowing for collaboration -across individuals and teams. We can collectively determine "how we work best" and document such guidelines in a -version-controlled repository with access to the collaborative tools that GitHub provides. - -Through this guide, we seek to promote a culture of continuous improvement, where feedback is encouraged, and processes -are regularly reviewed and updated to reflect evolving industry standards and emerging technologies - this is a living -document. - -Another goal to provide an equal footing for all people, regardless of their background and skill levels. Having -accessible, well-documented guidelines available to all people associated with the lab is a way to ensure all employees -(and students), regardless of background, have the same access to information. The lack of diversity within the fields -represented in Data Systems can be accounted for, in part, by how accessible - or not - the fields are. Prohibitive -costs, dearth of mentorship, strict mores and norms (think: expectations when finding an advisor or going to a -conference), and equal access to information all play a part in this overall accessibility. We can start to address -the last item on the list within our own workplace. In building this developer guide, we hope to create a successful -start for those new to the job or learning new skills. - -## Scope - -The developer guide aims to provide guidelines and recommendations, not mandates. It also aims to provide information -in a non-redundant way, and avoid re-writing what may already be well-documented somewhere on the internet. Instead of -describing a topic in detail, the developer guide attempts to answer the question -- "How do I apply this concept in the -context of my work in Data Systems?" +This repository contains the source code for the LASP developer guide. For more information about purpose, motivation, +scope, and contents, see the developer guide here: http://lasp-developer-guide.readthedocs.io/. ## Contributing If you would like to contribute changes to the content of this repository, do the following: + 1. Create a fork of this repository 2. Make a local clone of your fork: diff --git a/docs/source/index.rst b/docs/source/index.rst index 9760354..22916ca 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,6 +3,53 @@ LASP Developer's Guide Welcome to the LASP Developer's Guide! +Purpose +------- + +The purpose of this repository is to provide a collection of documented guidelines for software development workflows +and processes commonly used within Data Systems in order to assist developers in accomplishing their work. The developer +guide is managed within this version-controlled GitHub repository as to allow for the collaborative creation and +maintenance of the guidelines. + +Motivation +---------- + +The motivation for this effort is two-fold: + - We are motivated by [Goal 3.1](https://confluence.lasp.colorado.edu/display/DS/2024-2027+Data+Systems+Strategic+Plan#id-20242027DataSystemsStrategicPlan-goal3) +from the 2024-2027 Data Systems Strategic Plan, which states "Create a set of living DS best practices and training +guides that include standard processes and expectations for common tasks". + - With the push towards open science and access (see [NASA’s directive SPD-41a](https://science.nasa.gov/researchers/open-science/science-information-policy/)) +we hope to also embody this openness in our internal processes. + +Historically, such documentation has been spread over multiple pages and spaces within confluence and specific projects. +The developer guide endeavors to bring these resources together in one centralized space, allowing for collaboration +across individuals and teams. We can collectively determine "how we work best" and document such guidelines in a +version-controlled repository with access to the collaborative tools that GitHub provides. + +Through this guide, we seek to promote a culture of continuous improvement, where feedback is encouraged, and processes +are regularly reviewed and updated to reflect evolving industry standards and emerging technologies - this is a living +document. + +Another goal to provide an equal footing for all people, regardless of their background and skill levels. Having +accessible, well-documented guidelines available to all people associated with the lab is a way to ensure all employees +(and students), regardless of background, have the same access to information. The lack of diversity within the fields +represented in Data Systems can be accounted for, in part, by how accessible - or not - the fields are. Prohibitive +costs, dearth of mentorship, strict mores and norms (think: expectations when finding an advisor or going to a +conference), and equal access to information all play a part in this overall accessibility. We can start to address +the last item on the list within our own workplace. In building this developer guide, we hope to create a successful +start for those new to the job or learning new skills. + +Scope +----- + +The developer guide aims to provide guidelines and recommendations, not mandates. It also aims to provide information +in a non-redundant way, and avoid re-writing what may already be well-documented somewhere on the internet. Instead of +describing a topic in detail, the developer guide attempts to answer the question -- "How do I apply this concept in the +context of my work in Data Systems?" + +Contents +-------- + .. toctree:: :maxdepth: 1 From b1004ed29d2ab2b71fa169107f69b973c08db2b9 Mon Sep 17 00:00:00 2001 From: Matthew Bourque Date: Wed, 25 Sep 2024 14:45:59 -0600 Subject: [PATCH 2/2] Small changes to make things read better --- docs/source/index.rst | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 22916ca..ec429e2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,25 +1,23 @@ -LASP Developer's Guide -====================== - Welcome to the LASP Developer's Guide! +====================================== Purpose ------- -The purpose of this repository is to provide a collection of documented guidelines for software development workflows -and processes commonly used within Data Systems in order to assist developers in accomplishing their work. The developer -guide is managed within this version-controlled GitHub repository as to allow for the collaborative creation and -maintenance of the guidelines. +The purpose of this website is to provide a collection of documented guidelines for software development workflows and +processes commonly used within Data Systems in order to assist developers in accomplishing their work. The developer +guide is managed within a version-controlled `GitHub repository `_ as to allow +for the collaborative creation and maintenance of the guidelines. Motivation ---------- The motivation for this effort is two-fold: - - We are motivated by [Goal 3.1](https://confluence.lasp.colorado.edu/display/DS/2024-2027+Data+Systems+Strategic+Plan#id-20242027DataSystemsStrategicPlan-goal3) -from the 2024-2027 Data Systems Strategic Plan, which states "Create a set of living DS best practices and training -guides that include standard processes and expectations for common tasks". - - With the push towards open science and access (see [NASA’s directive SPD-41a](https://science.nasa.gov/researchers/open-science/science-information-policy/)) -we hope to also embody this openness in our internal processes. + - We are motivated by `Goal 3.1 `_ + from the 2024-2027 Data Systems Strategic Plan, which states "Create a set of living DS best practices and training + guides that include standard processes and expectations for common tasks". + - With the push towards open science and access (see `NASA’s directive SPD-41a `_) + we hope to also embody this openness in our internal processes. Historically, such documentation has been spread over multiple pages and spaces within confluence and specific projects. The developer guide endeavors to bring these resources together in one centralized space, allowing for collaboration @@ -27,8 +25,8 @@ across individuals and teams. We can collectively determine "how we work best" a version-controlled repository with access to the collaborative tools that GitHub provides. Through this guide, we seek to promote a culture of continuous improvement, where feedback is encouraged, and processes -are regularly reviewed and updated to reflect evolving industry standards and emerging technologies - this is a living -document. +are regularly reviewed and updated to reflect evolving industry standards and emerging technologies - these are a living +documents! Another goal to provide an equal footing for all people, regardless of their background and skill levels. Having accessible, well-documented guidelines available to all people associated with the lab is a way to ensure all employees @@ -44,8 +42,8 @@ Scope The developer guide aims to provide guidelines and recommendations, not mandates. It also aims to provide information in a non-redundant way, and avoid re-writing what may already be well-documented somewhere on the internet. Instead of -describing a topic in detail, the developer guide attempts to answer the question -- "How do I apply this concept in the -context of my work in Data Systems?" +describing a topic in detail, the developer guide attempts to answer the question -- *"How do I apply this concept in +the context of my work in Data Systems?"* Contents --------