owned this note   changed 7 months ago  
Linked with GitHub

Foundational Open Science Skills (FOSS) Lesson 3: Intro to Documentation

Date: 09/19/2024
Today Lead Instructor: Jeff, Michele
Today Helpers: Tina
Course Website: https://foss.cyverse.org/03_documentation_communication/
Hack(pad)-of-Hack(pads): https://hackmd.io/-4TgToyFRU2eX7lmDZLRnQ

Instant Feedback: (please complete before you leave class) Complete Form

Table of Contents

Agenda :stopwatch:

  • Welcome and week 3 review (10 minutes)
  • Introduction to Documentation (20 minutes)
  • BioBreak?
  • Building a GitHub Website using MkDocs (45 minutes)

Introduction to Documentation

Open Questions

Q: What types of communication do you regularly do? What modes do you use for them?

  • email +++++++++++
  • SLACK! +++++++++
  • Phone ++++++++
  • Zoom meetings+ +++++++++
  • Teams ++++
  • weekly group meetings +++++
  • face2face +++++++++

Q: What types of documentation do you regularly read? What types do you write? What do you use for this documentation?

  • Github issues ++++
  • Github Pages +++++++
  • Wikis +++

Q: What kind of organization/structure do you use for documentation?

  • GitHub README.md +++++
  • GitHub Wiki
  • Box/BoxHealth+++++
  • Google docs +++++++++
  • DropBox+++++

Q: What are the most significant barriers and challenges researchers face when attempting to communicate their work openly to a broader audience?

  • Building an audience/network on Twitter
  • Standing out among the sea of existing content
  • Making understandable documentation for scripts and software
  • Limitations around participant confidentiality
  • TIME!!! These products are not rewarded adequately in the academy and thus draw time away from tasks we "should" be completing +++
  • Using the right language to reach people outside of your specific field +1
  • Struggling to avoid more technical words in their communication
  • Communicating in a way that is culturally sensitive but relevant to broader audience
  • Making information concise and yet explanatory
  • Knowing your audience

:toilet: BioBreak (10 minutes) :coffee: :tea: :cookie:

Useful links

Jekyll theme:
- https://academicpages.github.io/
- https://github.com/academicpages/academicpages.github.io

MkDocs-material theme:
- https://cosimichele.github.io/academicpages-mkdocs/
- https://github.com/CosiMichele/academicpages-mkdocs

Making a GitHub Pages website

ghpages.yml

name: Publish docs via GitHub
on:
  push:
    branches:
      - main

jobs:
  build:
    name: Deploy docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: 3.9
      - name: run requirements file
        run:  pip install -r requirements.txt 
      - name: Deploy docs
        run: mkdocs gh-deploy --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mkdocs.yml

site_name: FOSS 24 Spring GitHub tutorial
site_description: Site for tutorial for FOSS 24 attedees
site_author: Michele Cosi
site_url: https://cosimichele.github.io/foss24-spring-gitpages

# Repository
repo_name: foss24-spring-gitpages
repo_url: https://github.com/CosiMichele/foss24-spring-gitpages
edit_uri: edit/main/docs/
# Copyright
copyright: 'Copyright © 2023 - 2024'


# Configuration
theme:
    name: material
highlightjs: true
font:
    text: Roboto
    code: Regular
palette:
    scheme: default

# Features  
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.tabs.sticky
- navigation.indexes
- navigation.top
- toc.follow

# 404 page
static_templates:
    - 404.html

# Search feature
include_search_page: false
search_index_only: true

# Palette and theme (uses personalized colours)
language: en
palette:
    primary: custom
    accent: custom
icon:
    logo: material/cogs
    favicon: material/cogs

# Page tree
nav:
- Home: index.md

# Extra Plugins
plugins:
    - search
    - mkdocstrings
    - git-revision-date
    - mkdocs-jupyter:
        include_source: True
        ignore_h1_titles: True

# Extensions (leave as is)
markdown_extensions:
- admonition
- abbr
- attr_list
- def_list
- footnotes
- meta
- md_in_html
- toc:
    permalink: true
    title: On this page
- pymdownx.arithmatex:
    generic: true
- pymdownx.betterem:
    smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.emoji:
    emoji_index: !!python/name:materialx.emoji.twemoji
    emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.magiclink:
    repo_url_shorthand: true
    user: squidfunk
    repo: mkdocs-material
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.tabbed
- pymdownx.tasklist:
    custom_checkbox: true
- pymdownx.tilde

Instant Feedback: (please complete before you leave class) Complete Form

Select a repo