Skip to content

Commit

Permalink
[STY] fix some styling issues in the reports (#596)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Remi-Gau
Remi-Gau authored Dec 12, 2024
1 parent 1eb4eed commit 5357c23
Show file tree
Hide file tree
Showing 4 changed files with 46 additions and 144 deletions.
28 changes: 13 additions & 15 deletions docs/collaboration/reports/google_summer/2018-gsoc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,21 +88,21 @@ and many more.
:o: **Problem** Engage more users

:heavy_check_mark: **Solution** In person, our team continued to spread the word
about the project during any relevant events. Online, we created an
[animated video](https://camo.githubusercontent.com/aada478abaddf957a3622589a5c370f11bf67642/687474703a2f2f696d672e796f75747562652e636f6d2f76692f425964686a5675427347302f302e6a7067)
to summarize the general idea and make the first step that much easier. We
developed
[extensive contribution guidelines](https://github.com/bids-standard/bids-starter-kit/blob/main/CONTRIBUTING.md)
to help new contributors add their expertise to the project. We include how to
[get in touch](https://github.com/bids-standard/bids-starter-kit/blob/main/CONTRIBUTING.md#get-in-touch),
[write in markdown](https://github.com/bids-standard/bids-starter-kit/blob/main/CONTRIBUTING.md#writing-in-markdown),
[submit a pull request](https://github.com/bids-standard/bids-starter-kit/blob/main/CONTRIBUTING.md#making-a-change-with-a-pull-request)
and explanations of where to put
[useful code or links in the wiki](https://github.com/bids-standard/bids-starter-kit/blob/main/CONTRIBUTING.md#where-to-start-wiki-code-and-templates).
about the project during any relevant events.
Online, we created an animated video
to summarize the general idea and make the first step that much easier.
We developed
[extensive contribution guidelines](../../bids_github/CONTRIBUTING.md)
to help new contributors add their expertise to the project.
We include how to get in touch,
write in markdown,
[submit a pull request](../../bids_github/CONTRIBUTING.md#making-a-change-with-a-pull-request)
and explanations of where to put useful code or links in the wiki.
The licence on our repository is CC-BY and these guidelines have already been
incorporated into other open source neuroimaging projects such as
[NiBetaSeries](https://nibetaseries.readthedocs.io/en/stable/). We also used the
[“good-first-issue” principle](https://github.com/bids-standard/bids-starter-kit/blob/main/CONTRIBUTING.md#where-to-start-issue-labels)
[NiBetaSeries](https://nibetaseries.readthedocs.io/en/stable/).
We also used the
“good-first-issue” principle
to periodically leave small mistakes in our repository unfixed, such as a typo
or an undefined term in the glossary. Then, we would send out a request and
guide a new contributor through the process of using the repository.
Expand Down Expand Up @@ -155,6 +155,4 @@ University, Canada

Email: `[email protected]`

Github: [Park-Patrick](https://github.com/Park-Patrick)

Note: [INCF](https://incf.org) was the supporting umbrella organization for this BIDS Google Summer of Code project.
154 changes: 26 additions & 128 deletions docs/collaboration/reports/google_summer/2024-gsod.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
# BIDS - INCF 2024 Google Season of Docs Case Study

:o: Umbrella Organization: [INCF](incf.org) - International Neuroinformatics Coordinating Facility

:o: Project Organization: [BIDS](https://bids.neuroimaging.io/) - Brain Imaging Data Structure

:o: Project Title: [Streamlining the BIDS Online Presence](https://www.incf.org/activities/gsod)
- Umbrella Organization: [INCF](https://www.incf.org) - International Neuroinformatics Coordinating Facility
- Project Organization: [BIDS](https://bids.neuroimaging.io/) - Brain Imaging Data Structure
- Project Title: [Streamlining the BIDS Online Presence](https://www.incf.org/activities/gsod)

## About BIDS

Expand All @@ -27,7 +25,7 @@ Case Study Authors:

This project was trying to improve the BIDS Online Presence, which consists primarily of its informational websites and the BIDS specification.
We were able to migrate away from a multitude of websites and condense down to mainly the one “New” BIDS Website.
Overall the project was very succesful with a wealth of work put in by the tech writer and mentors.
Overall the project was very successful with a wealth of work put in by the tech writer and mentors.
One lesson learned was we could have budgeted more for mentor time as it required more mentor time than anticipated.
For other open-source volunteer or community-driven projects in need of coentralizing and streamlining their own online presence,
this is a great program if you can define most of the tasks early on and dedicate mentor time alongside tech writer time during the project.
Expand All @@ -47,58 +45,21 @@ Improvements from this project satisfied FAIR guiding principles and improved th

### Proposal Creation Process

*How did you come up with your Google Season of Docs proposal? What process did your organization use to decide on an idea? How did you solicit and incorporate feedback? Who participated in the process? How long did it take?*

The BIDS maintainers, steering group, and BIDS online presence working group all saw a need for BIDS to improve and centralize its online resources.
One of the BIDS maintainers, Christine Rogers, had worked with Google Season of Docs before with success and suggested we partner with INCF to make progress on the website and documentation improvement projects.
Primarily Christine and Eric Earl (chair of the BIDS online presence working group and another BIDS maintainer) drove the project proposal forward with prioritization oversight from the online presence working group.
The brief proposal format was effectively developed through several consultative meetings and rounds of drafting.

### Budget

<table>
<tr>
<td>How much money did you ask for?
</td>
<td>$6,500 USD
</td>
</tr>
<tr>
<td>How did you come up with this estimate?
</td>
<td>Writer stipend: $5000 \
Mentor stipend: $500 * 3 mentors
<p>
(following GSOC practice)
</td>
</tr>
<tr>
<td>How many hours of work did you budget for the project?
</td>
<td>Writer: 4 h / wk \
Mentors; 1 h / wk * 4 mentors = 4 h / wk
</td>
</tr>
<tr>
<td>How many hours of work were actually needed for the project?
</td>
<td>Writer: 5 h / wk \
Mentors: 1.5 h / week * 4 mentors = 6 h / wk
</td>
</tr>
<tr>
<td>What other expenses did you include in your budget?
</td>
<td>None
</td>
</tr>
<tr>
<td>Did you run into any budget surprises during the project (for example mis-estimates)? If so, please explain.
</td>
<td>Mentor time underestimated. Would allocate more for additional mentors or more mentor time.
</td>
</tr>
</table>
| | |
| -------------------------------------------------------------------------------------------------------------| -------------------------------------------------------------------------------------------- |
| How much money did you ask for? | 6500$ USD |
| How did you come up with this estimate? | Writer stipend: 5000$ <br> Mentor stipend: 500$ * 3 mentors <br> (following GSOC practice) |
| How many hours of work did you budget for the project? | Writer: 4 h / wk <br> Mentors: 1 h / wk * 4 mentors = 4 h / wk |
| How many hours of work were actually needed for the project? | Writer: 5 h / wk <br> Mentors: 1.5 h / week * 4 mentors = 6 h / wk |
| What other expenses did you include in your budget? | None |
| Did you run into any budget surprises during the project (for example mis-estimates)? If so, please explain. | Mentor time underestimated. Would allocate more for additional mentors or more mentor time. |

### Technical Writer Recruitment

Expand Down Expand Up @@ -131,85 +92,22 @@ And finally, October and November brought the BIDS Impact page together to wrap

#### Planned Deliverables

<table>
<tr>
<td><strong>Deliverable</strong>
</td>
<td><strong>% Complete</strong>
</td>
<td><strong>Relevant Links</strong>
</td>
<td><strong>Notes</strong>
</td>
</tr>
<tr>
<td>Consolidate into one website
</td>
<td>100%
</td>
<td><a href="https://bids-website.readthedocs.io/">https://bids-website.readthedocs.io/</a>
</td>
<td>Dev site - Planning launch in Q1 2025 to replace the old BIDS website at <a href="https://bids.neuroimaging.io/">https://bids.neuroimaging.io/</a>
</td>
</tr>
<tr>
<td>Implement a more friendly main website structure and improve navigation
</td>
<td>100%
</td>
<td><a href="https://github.com/bids-standard/bids-website/blob/main/mkdocs.yml#L88">https://github.com/bids-standard/bids-website/blob/main/mkdocs.yml#L88</a>
</td>
<td>User feedback indicates this created significant improvement ( See: Metrics)
</td>
</tr>
<tr>
<td>New BIDS Impact page
</td>
<td>100%
</td>
<td><a href="https://bids-website.readthedocs.io/en/latest/impact/index.html">https://bids-website.readthedocs.io/en/latest/impact/index.html</a>
</td>
<td>Expanded and improved with more metrics and relevant context
</td>
</tr>
<tr>
<td>Categorize and add clear summaries to each webpage
</td>
<td>100%
</td>
<td><a href="https://github.com/bids-standard/bids-website/pull/498">https://github.com/bids-standard/bids-website/pull/498</a>
</td>
<td>Each page now has a lead paragraph
</td>
</tr>
<tr>
<td>Synthesized and enabled gathering of user-feedback and user-testing
</td>
<td>100%
</td>
<td>
</td>
<td>Developed a follow-up survey and collated findings from all community feedback. Helped synthesize metrics and inputs for annual community presentation.
</td>
</tr>
<tr>
<td>Add a feedback form within the main website
</td>
<td>100%
</td>
<td>
</td>
<td>Giscus at the bottom of the front page was re-scoped and implemented by a mentor
</td>
</tr>
</table>
| Deliverable | % Complete | Relevant Links | Notes |
| ----------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Consolidate into one website | 100% | [new BIDS wesbite](https://bids-website.readthedocs.io/) | Dev site - Planning launch in Q1 2025 to replace the old BIDS website at <https://bids.neuroimaging.io/> |
| Implement a more friendly main website structure and improve navigation | 100% | [mkdocs TOC configuration](https://github.com/bids-standard/bids-website/blob/main/mkdocs.yml#L88) | User feedback indicates this created significant improvement ( See: [Metrics](#metrics)) |
| New BIDS Impact page | 100% | [new impact page](https://bids-website.readthedocs.io/en/latest/impact/index.html) | Expanded and improved with more metrics and relevant context |
| Categorize and add clear summaries to each webpage | 100% | [Pull request #498](https://github.com/bids-standard/bids-website/pull/498) | Each page now has a lead paragraph. |
| Synthesized and enabled gathering of user-feedback and user-testing | 100% | | Developed a follow-up survey and collated findings from all community feedback. Helped synthesize metrics and inputs for annual community presentation. |
| Add a feedback form within the main website | 100% | | Giscus at the bottom of the front page was re-scoped and implemented by a mentor |

The above table summarizes the many changes across several repositories (pull requests linked here):

The above table summarizes the many changes across several repositories (PRs linked here):
- [BIDS Website repo](https://github.com/bids-standard/bids-website/pulls?q=+is%3Apr+author%3Aiamdamion) and related repositories with content:

- [BIDS Website repo](https://github.com/bids-standard/bids-website/pulls?q=+is%3Apr+author%3Aiamdamion) and sub/related repos with content:
- [BIDS-Apps Repo](https://github.com/bids-apps/bids-apps.github.io/pull/140)
- [BIDS Execution Spec](https://github.com/bids-standard/execution-spec/pull/24)
- [BIDS Extensions repo](https://github.com/bids-standard/bids-extensions/pull/35)
- [BIDS-Apps Repo](https://github.com/bids-apps/bids-apps.github.io/pull/140)
- [BIDS Execution Spec](https://github.com/bids-standard/execution-spec/pull/24)
- [BIDS Extensions repo](https://github.com/bids-standard/bids-extensions/pull/35)

#### Unplanned Deliverables

Expand Down
2 changes: 1 addition & 1 deletion docs/getting_started/folders_and_files/metadata/json.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,7 @@ Remember to install and call a package before using it.
- are no longer than 63 characters.

Many parts of JSON files are often loaded as
[`structures`](https://nl.mathworks.com/help/matlab/ref/struct.html) by MATLAB / Octave,
[`structures`](https://www.mathworks.com/help/matlab/ref/struct.html) by MATLAB / Octave,
where a `key` in a JSON file becomes `fieldname` in that structure.

Here is an example with a simple `example.json`
Expand Down
6 changes: 6 additions & 0 deletions md_link_check_config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,12 @@
},
{
"pattern": "^https://human-organ-atlas.esrf.eu.*"
},
{
"pattern": "^https://www.mathworks.com.*"
},
{
"pattern": "^https://www.seedsforchange.org.uk/consensus"
}
],
"timeout": "20s",
Expand Down

0 comments on commit 5357c23

Please sign in to comment.