From 5a4a11f98a86d0db596d24a200667a7963e9b3f7 Mon Sep 17 00:00:00 2001 From: Julie Lowndes Date: Fri, 20 Mar 2026 06:40:34 -0700 Subject: [PATCH 1/3] start to update blog documentation --- approach/documentation.qmd | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/approach/documentation.qmd b/approach/documentation.qmd index 8e9064d..424ff20 100644 --- a/approach/documentation.qmd +++ b/approach/documentation.qmd @@ -26,6 +26,11 @@ Blog posts take time. A lot of time. And they often feel extra, especially in a 3. **Share with co-authors early.** But not too early. Often we are trying to do the legwork to get a blog post structured and drafted describing the work they've already put into the event or slides. So along with the next point, do this until it's good enough, and share! 4. **Be ok with imperfect, and done!** Yes, there is more to say if you put months of time into this. And we may find a sentence to be polished after posting, and that's ok. We aim to share ideas and momentum from our community with the mindset that sharing some and imperfectly is better than silence. +When we draft posts we do in Google Docs for easy edits then move to Quarto. We have a Google folder [ OpenscapesCommsEngagement > Blogs ] full of google docs where we start drafts and ask others to review, comment, suggest edits as needed. The workflow:creating the blogpost in google docs. Review/approval. Move to a qmd file (can copy from a formatted google doc to a qmd in Visual Editor mode of RStudio or Positron, then edit further as needed) and then PR of the qmd file to the main repo. + +If we're drafting in Quarto first (which we have done to test/practice what it's like to use GitHub review features) we can borrow a practice from rOpenSci from Stef: "we moved to 80 char lines for that reason. So much easier to review & make suggested commits." + + ## Make our documentation citable We want to share our documentation in a way that other people can find it, use it, improve it, and cite it. We use the Zenodo repository for this purpose. Every upload to Zenodo is assigned a Digital Object Identifier (DOI), to make it citable and trackable. From e621cf334a7a9a65b0aa7af60e84938ae8eb1cb3 Mon Sep 17 00:00:00 2001 From: ronnyhdez Date: Sat, 21 Mar 2026 09:53:42 -0600 Subject: [PATCH 2/3] Ref #152 move paragraphs to 80 char lines for easier review At least in the blog section --- approach/documentation.qmd | 62 ++++++++++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 12 deletions(-) diff --git a/approach/documentation.qmd b/approach/documentation.qmd index 424ff20..97ca4b8 100644 --- a/approach/documentation.qmd +++ b/approach/documentation.qmd @@ -17,18 +17,56 @@ We can build out this page with different ways we do documentation, but a first ## Blogs -We write a lot of blog posts. They give visibility to things that are otherwise hidden. One example is writing a blog post for a workshop on [Audience Building and Strategic Planning](https://www.openscapes.org/blog/2021/01/06/audience-building/). This was a lot of work to put together, and we think it's valuable for others! In addition to posting the slides, how could we amplify it more and tell a story around those slides that make it more sharable? That's right, a blog post. - -Blog posts take time. A lot of time. And they often feel extra, especially in a culture of needing peer-reviewed publications. But they are super valuable, and important. So, here are some strategies we use to write blogs: - -1. **Reuse structure.** Copy-paste a previous blog post structure. Ah, yes, we have the publish date, the title, the authors up top, some italics introducing what this is and who the authors are, with quick links. Then, 3-4 headers with up to 3 paragraphs each and a few pictures. Delete the content but start from there. -2. **Reuse content.** We spend a lot of time planning events and slides - reuse them! Copy text directly from the Agenda docs, and from the slides! Add text to shape the story, but then copy-paste as much as possible. This can be harder with posts that synthesize events (like the [2022 ESIP blog post](https://www.openscapes.org/blog/2021/01/06/audience-building/) and upcoming post for 2023). These events require more time to rewatch the recording and synthesize and identify themes, but there is still a lot to be reused, especially quotes! -3. **Share with co-authors early.** But not too early. Often we are trying to do the legwork to get a blog post structured and drafted describing the work they've already put into the event or slides. So along with the next point, do this until it's good enough, and share! -4. **Be ok with imperfect, and done!** Yes, there is more to say if you put months of time into this. And we may find a sentence to be polished after posting, and that's ok. We aim to share ideas and momentum from our community with the mindset that sharing some and imperfectly is better than silence. - -When we draft posts we do in Google Docs for easy edits then move to Quarto. We have a Google folder [ OpenscapesCommsEngagement > Blogs ] full of google docs where we start drafts and ask others to review, comment, suggest edits as needed. The workflow:creating the blogpost in google docs. Review/approval. Move to a qmd file (can copy from a formatted google doc to a qmd in Visual Editor mode of RStudio or Positron, then edit further as needed) and then PR of the qmd file to the main repo. - -If we're drafting in Quarto first (which we have done to test/practice what it's like to use GitHub review features) we can borrow a practice from rOpenSci from Stef: "we moved to 80 char lines for that reason. So much easier to review & make suggested commits." +We write a lot of blog posts. They give visibility to things that are otherwise +hidden. One example is writing a blog post for a workshop on [Audience Building +and Strategic Planning](https://www.openscapes.org/blog/2021/01/06/audience-building/). +This was a lot of work to put together, and we think it's valuable for others! In +addition to posting the slides, how could we amplify it more and tell a story +around those slides that make it more sharable? That's right, a blog post. + +### Strategies to write a blog post + +Blog posts take time. A lot of time. And they often feel extra, especially in a +culture of needing peer-reviewed publications. But they are super valuable, and +important. So, here are some strategies we use to write blogs: + +1. **Reuse structure.** Copy-paste a previous blog post structure. Ah, yes, we + have the publish date, the title, the authors up top, some italics + introducing what this is and who the authors are, with quick links. Then, 3-4 + headers with up to 3 paragraphs each and a few pictures. Delete the content but + start from there. + +2. **Reuse content.** We spend a lot of time planning events and slides - reuse + them! Copy text directly from the Agenda docs, and from the slides! Add text + to shape the story, but then copy-paste as much as possible. This can be harder + with posts that synthesize events (like the [2022 ESIP blog + post](https://www.openscapes.org/blog/2021/01/06/audience-building/) and + upcoming post for 2023). These events require more time to rewatch the recording + and synthesize and identify themes, but there is still a lot to be reused, + especially quotes! + +3. **Share with co-authors early.** But not too early. Often we are trying to + do the legwork to get a blog post structured and drafted describing the work + they've already put into the event or slides. So along with the next point, do + this until it's good enough, and share! + +4. **Be ok with imperfect, and done!** Yes, there is more to say if you put + months of time into this. And we may find a sentence to be polished after + posting, and that's ok. We aim to share ideas and momentum from our community + with the mindset that sharing some and imperfectly is better than silence. + +When we draft posts we do in Google Docs for easy edits then move to Quarto. We +have a Google folder [ OpenscapesCommsEngagement > Blogs ] full of google docs +where we start drafts and ask others to review, comment, suggest edits as +needed. The workflow:creating the blogpost in google docs. Review/approval. Move +to a qmd file (can copy from a formatted google doc to a qmd in Visual Editor +mode of RStudio or Positron, then edit further as needed) and then PR of the qmd +file to the main repo. + +If we're drafting in Quarto first (which we have done to test/practice what it's +like to use GitHub review features) we can borrow a practice from rOpenSci from +Stef: "we moved to 80 char lines for that reason. So much easier to review & +make suggested commits." ## Make our documentation citable From d9021dff748e4b37c357f0d89cc21b5ea8b1e17c Mon Sep 17 00:00:00 2001 From: ronnyhdez Date: Sat, 21 Mar 2026 11:23:11 -0600 Subject: [PATCH 3/3] Ref #152 include subsections and metadata structure --- approach/documentation.qmd | 39 +++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/approach/documentation.qmd b/approach/documentation.qmd index 97ca4b8..8cd8797 100644 --- a/approach/documentation.qmd +++ b/approach/documentation.qmd @@ -55,19 +55,36 @@ important. So, here are some strategies we use to write blogs: posting, and that's ok. We aim to share ideas and momentum from our community with the mindset that sharing some and imperfectly is better than silence. -When we draft posts we do in Google Docs for easy edits then move to Quarto. We +### Workflow + +We draft posts in Google Docs for easy edits then move to Quarto. We have a Google folder [ OpenscapesCommsEngagement > Blogs ] full of google docs where we start drafts and ask others to review, comment, suggest edits as -needed. The workflow:creating the blogpost in google docs. Review/approval. Move -to a qmd file (can copy from a formatted google doc to a qmd in Visual Editor -mode of RStudio or Positron, then edit further as needed) and then PR of the qmd -file to the main repo. - -If we're drafting in Quarto first (which we have done to test/practice what it's -like to use GitHub review features) we can borrow a practice from rOpenSci from -Stef: "we moved to 80 char lines for that reason. So much easier to review & -make suggested commits." - +needed. + +All the draft docs share a template which includes the following metadata: + +``` +Publish date: +Location: +URL: +Title: +Authors: +Image: +``` + +The steps to create a blogpost are: + + 1. Create the blogpost in google docs. + 2. Ask others to review/approve. + 3. Move contents to a qmd file (can copy from a formatted google doc to a qmd + in Visual Editor mode of RStudio or Positron, then edit further as needed) + 4. Finally, create a Pull Request of the qmd file to the main + [repo](https://github.com/Openscapes/approach-guide). + +TODO: When including text in a Quarto file, wrap at lines at ~80 characters. +This improves readability in Git diffs and makes code review and suggested +eddits easier. ## Make our documentation citable