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..ec429e2 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,7 +1,52 @@ -LASP Developer's Guide -====================== - Welcome to the LASP Developer's Guide! +====================================== + +Purpose +------- + +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 `_ + 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 +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 - 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 +(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