From 30687268803e214ccb2df938c769ceb31087ea01 Mon Sep 17 00:00:00 2001 From: Matthew Bourque Date: Mon, 11 Aug 2025 16:35:27 -0600 Subject: [PATCH 1/3] expanded contributor docs --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7f87b11..c7e9fff 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,61 @@ # developer-guide -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/. +This repository contains the source code for the LASP developer guide. This README serves as a guide for those who wish +to contribute. For more information about purpose, motivation, scope, and contents of the developer guide, see the +developer guide homepage here: http://lasp-developer-guide.readthedocs.io/. ## Contributing +### Markdown + +This project uses the Markdown language as the source code for all documentation. +[This Markdown Guide](markdownguide.org) is a good resource for learning/troubleshooting Markdown syntax (google, +StackOverflow, and ChatGPT are also useful for this). Additionally, new contributors are encouraged to look through the +existing documents for examples on how to use Markdown and how to contribute with consistent formatting. + +### Organization + +Documents in this developer guide are mainly organized by topic, and is subject to change as more documents are added +and the project evolves. If it is not clear where to place a new document, feel free to open a GitHub issue so that the +larger group of developers can discuss it. + +### Consistency in formatting, language, and tone + +We aim to have a consistent tone and use of language throughout the documentation. Some things to keep in mind when +contributing: + +* Avoid sharing opinions about topics without supporting facts +* Stick to third-person language and avoid using first-person +* Avoid jargon, acronyms, or abbreviations unless they are defined +* Keep sentences and paragraphs concise—break up long blocks of text +* Follow a consistent capitalization style for headings, code terms, proper nouns, etc +* Format code snippets consistently (indentation, language tags for syntax highlighting). + +### What is out of scope + +* Do not include any credentials, usernames, passwords, etc. +* Do not include any material that is considered Controlled Unclassified Information (CUI) +* Do not include informal meeting notes + +### Template + +Please refer to the [guideline template] markdown file as a template for new guidelines. This template +should be considered as guidance, and not a hard rule -- sections may be removed, added, or edited based +on the contributor's discretion and what makes sense for the topic. + +### How to view the documentation as it appears on ReadTheDocs + +It is often helpful to view what the final product will look like while developing. To do this, one can build the +docs locally and view them in a local browser: + +```bash +cd docs/ +make clean && make html +open docs/build/html/index.html +``` + +### git Workflow + If you would like to contribute changes to the content of this repository, do the following: 1. Create a fork of this repository From 34e5d02cf87fd71094dd70c9e66739056f50bf62 Mon Sep 17 00:00:00 2001 From: Matthew Bourque Date: Mon, 11 Aug 2025 16:40:11 -0600 Subject: [PATCH 2/3] PR review suggestions from robot overlord --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c7e9fff..d0e0e91 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ developer guide homepage here: http://lasp-developer-guide.readthedocs.io/. ### Markdown This project uses the Markdown language as the source code for all documentation. -[This Markdown Guide](markdownguide.org) is a good resource for learning/troubleshooting Markdown syntax (google, +[This Markdown Guide](https://markdownguide.org) is a good resource for learning/troubleshooting Markdown syntax (google, StackOverflow, and ChatGPT are also useful for this). Additionally, new contributors are encouraged to look through the existing documents for examples on how to use Markdown and how to contribute with consistent formatting. @@ -39,9 +39,10 @@ contributing: ### Template -Please refer to the [guideline template] markdown file as a template for new guidelines. This template -should be considered as guidance, and not a hard rule -- sections may be removed, added, or edited based -on the contributor's discretion and what makes sense for the topic. +Please refer to the +[guideline template](https://github.com/lasp/developer-guide/blob/main/guideline_template.md) markdown file as a +template for new guidelines. This template should be considered as guidance, and not a hard rule -- sections may be +removed, added, or edited based on the contributor's discretion and what makes sense for the topic. ### How to view the documentation as it appears on ReadTheDocs @@ -51,7 +52,7 @@ docs locally and view them in a local browser: ```bash cd docs/ make clean && make html -open docs/build/html/index.html +open build/html/index.html ``` ### git Workflow From 060d5d39a84a78449021695f8d14d9178c7b1142 Mon Sep 17 00:00:00 2001 From: Matthew Bourque Date: Tue, 12 Aug 2025 11:34:26 -0600 Subject: [PATCH 3/3] PR Review suggestions --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d0e0e91..13edfc3 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ contributing: * Avoid sharing opinions about topics without supporting facts * Stick to third-person language and avoid using first-person * Avoid jargon, acronyms, or abbreviations unless they are defined -* Keep sentences and paragraphs concise—break up long blocks of text -* Follow a consistent capitalization style for headings, code terms, proper nouns, etc +* Keep sentences and paragraphs concise; break up long blocks of text +* Follow a consistent capitalization style for headings, code terms, proper nouns, etc. * Format code snippets consistently (indentation, language tags for syntax highlighting). ### What is out of scope