diff --git a/.github/toc-generator.yml b/.github/toc-generator.yml deleted file mode 100644 index 935320f..0000000 --- a/.github/toc-generator.yml +++ /dev/null @@ -1,10 +0,0 @@ -# TOC Generator Configuration - -# TOC settings -TOC_TITLE: "## Table of Contents" -FOLDING: false -MAX_HEADER_LEVEL: 4 - -# Marker comment settings -OPENING_COMMENT: "" -CLOSING_COMMENT: "" \ No newline at end of file diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..eaa48a7 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,41 @@ +name: Deploy docs + +on: + push: + branches: + - master + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Build docs + run: | + pip install zensical + zensical build + + - uses: actions/upload-pages-artifact@v3 + with: + path: site/ + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 0000000..2c64200 --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,18 @@ +name: Markdown Lint + +on: + push: + pull_request: + workflow_dispatch: + +jobs: + lint: + name: Markdown Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Run markdownlint + uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: "docs/**/*.md" diff --git a/.github/workflows/spelling.yml b/.github/workflows/spelling.yml index 63f50ae..ea2fe60 100644 --- a/.github/workflows/spelling.yml +++ b/.github/workflows/spelling.yml @@ -10,7 +10,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Spell Check uses: crate-ci/typos@master diff --git a/.github/workflows/update-toc.yml b/.github/workflows/update-toc.yml deleted file mode 100644 index 19dd882..0000000 --- a/.github/workflows/update-toc.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: Update Markdown TOC - -on: - push: - branches: - - master - workflow_dispatch: - -permissions: - contents: write - pull-requests: write - -jobs: - update-toc: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - token: ${{ github.token }} - - - name: Generate TOC - uses: technote-space/toc-generator@v4 - with: - GITHUB_TOKEN: ${{ github.token }} - TOC_TITLE: "## Table of Contents" - TARGET_PATHS: "group-syllabus/*.md" - FOLDING: false - CREATE_PR: true - PR_BRANCH_NAME: "update-toc-${PR_ID}" - PR_BRANCH_PREFIX: "toc-generator/" - PR_TITLE: "docs: update TOC" - COMMIT_MESSAGE: "Update TOC in markdown files" - COMMIT_NAME: "GitHub Action" - COMMIT_EMAIL: "action@github.com" - MAX_HEADER_LEVEL: 4 diff --git a/.gitignore b/.gitignore index 05320b5..565645e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,11 @@ -*tags -tags - -*.DS_Store +site/ .DS_Store - -**.aux -**.fls -**.synctex.gz -**.log -**.fdb_latexmk -**.bbl -**.blg -**.spl -**.out +*.aux +*.fdb_latexmk +*.fls +*.log +*.synctex.gz +*.bbl +*.blg +*.out +*.spl diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..c9f2b68 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,7 @@ +default: false + +# Rules that affect rendering +MD001: true # heading increment +MD032: true # blank lines around lists +MD012: true # no multiple blank lines +MD009: true # no trailing spaces diff --git a/docs/assets/extra.css b/docs/assets/extra.css new file mode 100644 index 0000000..c419e3f --- /dev/null +++ b/docs/assets/extra.css @@ -0,0 +1,65 @@ +:root { + --md-primary-fg-color: #292929; + --md-primary-fg-color--light: #3a3d3f; + --md-primary-fg-color--dark: #292929; + --md-accent-fg-color: #c0995e; + --md-accent-fg-color--transparent: #c0995e1a; +} + +[data-md-color-scheme="slate"] { + --md-default-bg-color: #292929; + --md-default-bg-color--light: #2e3133; + --md-default-bg-color--lighter: #3a3d3f; + --md-default-bg-color--lightest: #454849; +} + +.md-header { + background-color: #292929; + color: #fff; +} + +.md-header a, +.md-header__topic, +.md-header__title { + color: #fff; +} + +.md-header__topic { + font-weight: 700; +} + +a { + color: #c0995e; +} + +a:hover { + color: #d4b07a; +} + +.md-nav__link--active, +.md-nav__link:hover { + color: #c0995e; +} + +.md-nav--secondary .md-nav__link--active { + color: #c0995e; + background-color: transparent; + border-left: 2px solid #c0995e; +} + +.md-typeset a { + color: #c0995e; +} + +.md-typeset a:hover { + color: #d4b07a; +} + +.md-header__button.md-logo img { + height: 2.5rem; + width: auto; +} + +.md-footer { + display: none; +} diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 0000000..59b2e87 Binary files /dev/null and b/docs/assets/favicon.ico differ diff --git a/docs/assets/logo-icon.png b/docs/assets/logo-icon.png new file mode 100644 index 0000000..d35df89 Binary files /dev/null and b/docs/assets/logo-icon.png differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000..c854afd Binary files /dev/null and b/docs/assets/logo.png differ diff --git a/docs/assets/mathjax.js b/docs/assets/mathjax.js new file mode 100644 index 0000000..94d242a --- /dev/null +++ b/docs/assets/mathjax.js @@ -0,0 +1,12 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"], ["$", "$"]], + displayMath: [["\\[", "\\]"], ["$$", "$$"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; diff --git a/group-syllabus/challenges.md b/docs/group-syllabus/challenges.md similarity index 83% rename from group-syllabus/challenges.md rename to docs/group-syllabus/challenges.md index 628de74..3852396 100644 --- a/group-syllabus/challenges.md +++ b/docs/group-syllabus/challenges.md @@ -1,12 +1,5 @@ - - -## Table of Contents -- [Challenges and Mental Health](#challenges-and-mental-health) - - - -## Challenges and Mental Health +# Challenges and Mental Health The research or Ph.D. experience can be very challenging, sometimes in unexpected ways. It is common to experience mental health challenges during graduate school, or working on research and courses as an undergraduate. diff --git a/group-syllabus/computers.md b/docs/group-syllabus/computers.md similarity index 91% rename from group-syllabus/computers.md rename to docs/group-syllabus/computers.md index 763a514..5f072a0 100644 --- a/group-syllabus/computers.md +++ b/docs/group-syllabus/computers.md @@ -1,25 +1,14 @@ -## Computers +# Computers - - -## Table of Contents - -- [Georgia Tech](#georgia-tech) -- [University Clusters](#university-clusters) -- [DOE Labs](#doe-labs) -- [DOD Labs](#dod-labs) - - - -### Georgia Tech +## Georgia Tech * GT PACE Phoenix * User guide [here](https://docs.pace.gatech.edu/phoenix_cluster/gettingstarted_phnx/) * Login via `ssh @login-phoenix-rh9.pace.gatech.edu` to get the RHEL9 nodes - * Purpose: All-purpose campus resource of CPU and GPU jobs with a variety of hardware. + * Purpose: All-purpose campus resource of CPU and GPU jobs with a variety of hardware. * "Rules": Use the `embers` queue type to use idle nodes at zero cost. * To get access, let Spencer know, and he will fill out [this form](https://gatech.service-now.com/home?id=sc_cat_item&sys_id=61bc5e351b37f994a8622f4b234bcbf0). - + * GT ICE * [Resources/User guide](https://gatech.service-now.com/home?id=kb_article_view&sysparm_article=KB0042095) (click `Available Resources`, e.g.) * This looks like ~40 V100s, 8 A100s, 4 A40s, 20 RTX6000s, and 4 MI210s. @@ -27,7 +16,7 @@ * __Most GPU nodes sit idle__ * On those nodes: `MaxNodes=UNLIMITED MaxTime=18:00:00` -* GT Rogues Gallery +* GT Rogues Gallery * User guide [here](https://gt-crnch-rg.readthedocs.io/en/main/) * Purpose: Use of brand-new, forward-looking, or weird hardware. At the time of writing, it includes an NV H100 server, GH200 nodes, AMD MI210 GPU server, Bluefield-2/3 SmartNICs, RISC-V and Arm CPUs, etc. * "Rules": There are few rules; just follow the guidelines in the documentation. There are no limitations on hardware access/node hours. @@ -39,11 +28,11 @@ * "Rules": Be mindful of others' use of this machine as it does not have a scheduler. * Get access by emailing [Will Powell](mailto:will.powell@cc.gatech.edu), cc me. -### University Clusters +## University Clusters * ACCESS-CI computers * These are a set of university supercomputers listed [here](https://access-ci.org/resource-providers/). Each has its own user guide. At the time of writing, we have access to NCSA Delta (A100 GPUs), PSC Bridges2 (V100 GPUs), Purdue Anvil, and Texas A&M ACES (H100 GPUs), but we can change to others as needed. We primarily use NCSA Delta. - * Purpose: All-purpose resources for CPU and GPU simulation. + * Purpose: All-purpose resources for CPU and GPU simulation. * "Rules": Be mindful of the available node hours. Queue times might be long. * Our account number: * `PHY240200` (ACCESS-CI Maximize, NCSA Delta only) @@ -55,7 +44,7 @@ * The account name is `bdiy-delta-gpu` (ACCESS-CI Maximize) or `bbsc-delta-gpu` (ACCESS-CI Accelerate) for GPU resources * Replace `-gpu` with `-cpu` for CPU resources -### DOE Labs +## DOE Labs * Oak Ridge National Lab OLCF: Frontier/Wombat/Andes/etc. * Purpose @@ -83,7 +72,7 @@ * daas <- open this one * Can complete training and do other things here, like look at your WebCARS to get `WC_ID` (which you need to submit jobs) * Onto a computer remotely - * https://hpc.sandia.gov/access/ssh/ + * https://hpc.sandia.gov/access/ * Can do the below with DaaS (using my example username, `[usrname]`) * `ssh [usrname]@srngate.sandia.gov` * Passcode: `[PIN] + [yubikey one time pw]` @@ -111,11 +100,11 @@ * Can do the below with ssh (using my example username, `[usrname]`, for a specific LLNL machine, `[llnlmachine]`) * `ssh [usrname]@[llnlmachine].llnl.gov` * Passcode: `[PIN] + [rsa one time password]` - -### DOD Labs + +## DOD Labs * Department of Defense - * Anyone working on a DOD project can use [DOD HPCMP](https://www.hpc.mil/) (non-restricted) resources + * Anyone working on a DOD project can use [DOD HPCMP](https://www.hpc.mil/) (non-restricted) resources * The process of getting permissions to the non-restricted systems is a bit tedious but usually worth it * See [here](https://centers.hpc.mil/) for information on the available supercomputers * In particular, it's useful to keep an eye on [upcoming systems](https://centers.hpc.mil/systems/hardware.html#upcoming) @@ -123,10 +112,8 @@ * Talk to Spencer about getting access to a DOD machine if you are working on a DOD project * Subproject: `ONRDC51242690`, Group: `5124D690`, Project: `5124` * Site: `NAVY` - * nautilus + * nautilus * narwhal * Site: `ERDC` * carpenter * [Docs available here](https://centers.hpc.mil/users/docs/index.html#general) - - diff --git a/group-syllabus/doing-research.md b/docs/group-syllabus/doing-research.md similarity index 91% rename from group-syllabus/doing-research.md rename to docs/group-syllabus/doing-research.md index 90e58be..5847fe8 100644 --- a/group-syllabus/doing-research.md +++ b/docs/group-syllabus/doing-research.md @@ -1,38 +1,26 @@ -## Doing Research +# Doing Research The most important thing you do in graduate school is your research. It may seem obvious, but it's easy to lose track of the importance of your research amid all the other competing things you'll be asked to do as a student researcher: take classes, TA a class, submit and review papers, respond to paper reviews, organize/support various activities, etc. Some of these will be fun; many will feel more important at the time than making progress on your research. However, I would like you to prioritize your research and triage everything else after this. - - -## Table of Contents - -- [Selecting problems](#selecting-problems) -- [Expected Output](#expected-output) -- [Staying organized](#staying-organized) -- [Research Ideas and Directions](#research-ideas-and-directions) -- [Where to find ideas](#where-to-find-ideas) -- [Deciding what Ideas to Pursue](#deciding-what-ideas-to-pursue) - - - -### Selecting problems +## Selecting problems I advise students to aspire for impact in their work. Not by accident, this is also what I hope for in my work (which intersects and overlaps with your work). It's important to have _impact_ in mind when approaching problems (before you select and commit your time to them). Some guidelines on impact might include: -**What difference will this work make if you succeed?** +**What difference will this work make if you succeed?** + - Whose lives will be made better by this research? - How will this non-trivially improve upon current state-of-the-art? - Why is this one of the most important questions in the field? - Will it inspire a new class of methods, systems, tools, or computers? - **Who will care about it when you're done?** + - Will government agencies care? - Will industry/companies care? - Will other academics care enough to cite it? @@ -40,11 +28,12 @@ Some guidelines on impact might include: - Will anyone care about it 10, 20, 50 years in the future? **How will this change what other people (defined broadly) are doing?** + - Will other researchers change what they're working on after seeing your work? - Will practitioners do something different? - Will users adopt what you made/found/created? -### Expected Output +## Expected Output This is a note about what you should _strive_ to achieve in terms of output during your Ph.D. This differs from what I expect as your output, but what you should expect to _try_ to produce. @@ -76,7 +65,7 @@ This contribution is important for you to become known (even locally) for your e Note that if all of these are going on, and with other tasks and roles you will be taking, you are likely to have your plate feel very full. You'll need to balance your time and remember to take time off as needed. -### Staying organized +## Staying organized I dislike dictating how anyone works, so I minimize 'rules' and keep them flexible when possible. But, in general, it's very useful for me to keep track of my research work intentionally. @@ -90,7 +79,7 @@ Your research work should never live solely on one hard drive. I provide every student with a high-capacity backup hard drive. If you don't have one, please ask for one. -### Research Ideas and Directions +## Research Ideas and Directions _Have ideas!_ @@ -106,7 +95,7 @@ Ideas are everywhere; if you let yourself, you'll always have new ones. It can be easy to constantly find yourself submerged in the details of ongoing projects without popping up to think about and consider new projects, ideas, and directions. Both are important: a good scholar can move between levels of detail (i.e., "What's the right statistical technique for these data in this paper?" to "Which of these 5 new ideas would have the most impact?"). -### Where to find ideas +## Where to find ideas Some concrete ways in which one might find good ideas: @@ -130,7 +119,7 @@ You can use a file called `ideas.txt` to keep track of new ideas as they come to Importantly, while there is no such thing as "too many ideas," you shouldn't pursue more than a few at a time and carefully balance new ideas with ongoing work. This brings us to... -### Deciding what Ideas to Pursue +## Deciding what Ideas to Pursue What ideas and research direction should you pursue? Can a student choose any topic and research direction? @@ -140,7 +129,7 @@ It's an iterative, long-term process that results in alignment. This process starts when students pick to work with me and me with them because we have a shared interest. I am likely to steer new students towards directions and questions that are interesting (sometimes new, sometimes existing), especially projects that I have funding to work on. -But I try to entirely avoid "assigning" projects. +But I try to entirely avoid "assigning" projects. If the student is not excited and motivated about a research direction, the outcome will not likely be good (if you think I put you in this situation, please let me know so we can align). Similarly, students can pursue a project that I am less interested in, making me less engaged and less helpful as an advisor. The process of coming up with ideas, research questions, and project decisions thus naturally gravitates towards mutually interesting directions that overlap with existing or potential funding. @@ -148,5 +137,5 @@ The process of coming up with ideas, research questions, and project decisions t At the same time, "interest splits" happen, and students often pursue questions and directions. If there's no overlap, one option is to switch advisors. I have had students leave me to work with other advisors as it became clear that their pursuit and intellectual passion do not overlap with mine. -This is normal and healthy. +This is normal and healthy. What is _unhealthy_ is staying in an advising relationship even though passions do not overlap meaningfully. diff --git a/group-syllabus/faq.md b/docs/group-syllabus/faq.md similarity index 72% rename from group-syllabus/faq.md rename to docs/group-syllabus/faq.md index 093a05f..52e6352 100644 --- a/group-syllabus/faq.md +++ b/docs/group-syllabus/faq.md @@ -1,27 +1,3 @@ - - -## Table of Contents - -- [Frequently Asked Questions](#frequently-asked-questions) - - [General Questions](#general-questions) - - [What is the focus of the Computational Physics Group?](#what-is-the-focus-of-the-computational-physics-group) - - [How do I join the group?](#how-do-i-join-the-group) - - [Research and Collaboration](#research-and-collaboration) - - [How are research projects assigned?](#how-are-research-projects-assigned) - - [How often do we have group meetings?](#how-often-do-we-have-group-meetings) - - [What software/programming languages should I know?](#what-softwareprogramming-languages-should-i-know) - - [Academic Progress](#academic-progress) - - [What are the publication expectations?](#what-are-the-publication-expectations) - - [How do I know if I'm making good progress in my research?](#how-do-i-know-if-im-making-good-progress-in-my-research) - - [Resources and Support](#resources-and-support) - - [What computing resources are available?](#what-computing-resources-are-available) - - [Is there funding for conferences?](#is-there-funding-for-conferences) - - [What should I do if I'm struggling with my research or coursework?](#what-should-i-do-if-im-struggling-with-my-research-or-coursework) - - [Work-Life Balance](#work-life-balance) - - [What are the expectations for working hours/days?](#what-are-the-expectations-for-working-hoursdays) - - [Can I take vacation time? How much?](#can-i-take-vacation-time-how-much) - - # Frequently Asked Questions diff --git a/group-syllabus/figures.md b/docs/group-syllabus/figures.md similarity index 84% rename from group-syllabus/figures.md rename to docs/group-syllabus/figures.md index 81dec8c..fd4ee51 100644 --- a/group-syllabus/figures.md +++ b/docs/group-syllabus/figures.md @@ -1,34 +1,10 @@ -## Making figures +# Making figures **Companion documents: [Formatting your work](formatting.md)** - - -## Table of Contents - -- [This seems like a lot of work. Why am I doing this?](#this-seems-like-a-lot-of-work-why-am-i-doing-this) -- [What tool should you use to make figures?](#what-tool-should-you-use-to-make-figures) -- [Standalone compilation](#standalone-compilation) -- [Use of Git with Overleaf](#use-of-git-with-overleaf) -- [What if you have flow visualizations?](#what-if-you-have-flow-visualizations) -- [How to label sub-figures](#how-to-label-sub-figures) -- [Title](#title) -- [White space](#white-space) -- [Shared plots and legends](#shared-plots-and-legends) -- [Color bars](#color-bars) -- [Coordinate direction arrow triad.](#coordinate-direction-arrow-triad) -- [Axis bounds and ticks](#axis-bounds-and-ticks) -- [Axis labels](#axis-labels) -- [Information quantity](#information-quantity) -- [Consistency](#consistency) -- [Useful references](#useful-references) -- [Additional Resources](#additional-resources) - - - -See [here](../templates/paper/figures) for examples. - -### This seems like a lot of work. Why am I doing this? +See [here](https://github.com/comp-physics/group-docs/tree/master/templates/paper/figures) for examples. + +## This seems like a lot of work. Why am I doing this? From the formatting document: > For better or worse, the quality of your figures correlates with the perceived quality of your work. Just like the grammatical correctness of your writing, one might wonder if someone is sufficiently careful with their scientific work if they aren't very careful with their figures and presentation. @@ -39,24 +15,25 @@ I often also request small changes to figures to make them nicer. You might become quite frustrated if you have to re-do everything in Python + matplotlib, including re-running analysis, exporting the file, reuploading it, etc. With the method we use in the group, you pay the price __once__ to learn how to make very nice figures with TikZ/pgfplots, then reap the benefits until you decide to stop publishing your work (perhaps retirement). -### What tool should you use to make figures? +## What tool should you use to make figures? Use TikZ and PGFplots. These are TeX packages that provide a natural way to achieve consistency. -There is a steep learning curve, though the trade-off is worth it compared to their competitors. -The TeX stack exchange website regularly answers questions about these packages. +There is a steep learning curve, though the trade-off is worth it compared to their competitors. +The TeX stack exchange website regularly answers questions about these packages. A web search of almost any basic TikZ/PGF question will quickly flag an answer. -I can provide example `.tex` files for many things (like [here](../templates/paper/figures)), and you can gather examples from your colleagues as well as online (like [here](https://github.com/comp-physics/tikz-examples) and [here](https://github.com/comp-physics/TikZ-examples-2)). +I can provide example `.tex` files for many things (like [here](https://github.com/comp-physics/group-docs/tree/master/templates/paper/figures)), and you can gather examples from your colleagues as well as online (like [here](https://github.com/comp-physics/tikz-examples) and [here](https://github.com/comp-physics/TikZ-examples-2)). Some other nice features: -* Allows you to remake a figure very quickly (e.g., change a line of text in a program and recompile) + +* Allows you to remake a figure very quickly (e.g., change a line of text in a program and recompile) * Natural use of LaTeX fonts for text and equations -### Standalone compilation +## Standalone compilation Compile all your figures as standalone PDF documents. This is handy for your paper and for using them in presentations and other media. -With TikZ, this is quite easy, [here](../templates/paper/figures/slices.tex) is an example. +With TikZ, this is quite easy, [here](https://github.com/comp-physics/group-docs/blob/master/templates/paper/figures/slices.tex) is an example. Here is a template of sorts: ```tex \input{tikz_preamble} @@ -70,7 +47,7 @@ Here is a template of sorts: \end{document} ``` -where I have a separate file called `tikz_preamble.tex` that you can find [here](../templates/paper/figures/tikz_preamble.tex) that holds the relevant packages I need and defined the document style. +where I have a separate file called `tikz_preamble.tex` that you can find [here](https://github.com/comp-physics/group-docs/blob/master/templates/paper/figures/tikz_preamble.tex) that holds the relevant packages I need and defined the document style. Use Tikz option: @@ -79,14 +56,14 @@ Use Tikz option: ``` to make all the arrows in latex form. -### Use of Git with Overleaf +## Use of Git with Overleaf To create standalone figures in Overleaf, you should leverage its `git` feature. You simply go to the menu in the browser's top-left and then select `git`. This gives you a command to `git clone` your Overleaf document. You can `git add/commit/push` and `git pull` from this cloned directory. -### What if you have flow visualizations? +## What if you have flow visualizations? Images of complex simulations _require careful attention_! In some cases one will need to annotate them with axes labels, tick marks and labels, legends, and so on. @@ -99,12 +76,13 @@ I am not entirely sure how it works. I welcome recommendations on the best way to do this, but I know it is possible. Other rules: + * __Background color:__ Do not use background colors in your visualizations, e.g., the dark blue used in Paraview. Instead, use a white background! It will blend nicely into the document. To get Paraview to create a proper white background instead of a grayish one, make sure you [turn off the light kit for all 2D visualizations!](https://visualisation.gitlab-pages.dkrz.de/documentation/Paraview/Light/deactivate-light-kit/index.html). -* __File size:__ Do not use very large images. Images bigger than roughly 10MB are too large. +* __File size:__ Do not use very large images. Images bigger than roughly 10MB are too large. -### How to label sub-figures +## How to label sub-figures Label your sub-figures using font face and size consistent with the figure caption font face and size. Place your sub-figure labels (e.g., (a) and (b)) in a place that is not too obtrusive. @@ -113,15 +91,15 @@ Place your sub-figure labels (e.g., (a) and (b)) in a place that is not too obtr * If you need sub-captions, you should put the sub-figure labels below the center of the figure. Do not put the sub-figure captions directly below the sub-figures if you have no "real" caption (e.g., you are just labeling them (a) or (b), etc.); in this case, instead put them in one of the corners per above. -See the examples [here](../templates/paper/figures) for reference. +See the examples [here](https://github.com/comp-physics/group-docs/tree/master/templates/paper/figures) for reference. Place a space between your sub-figure labels (e.g., (a, b) instead of (a,b)). -### Title +## Title Your figures should not have titles. -### White space +## White space Minimize any excessive white space in journal/abstract figures. This helps match the figures with relevant text and makes the paper and figure more appealing. @@ -132,7 +110,7 @@ Figures should never go beyond the page margin. This principle is discussed more [here](https://bioinformatics-core-shared-training.github.io/effective-figure-design/DesigningEffectiveScientificFigures_Zabala_afternoon_v00.pdf). -### Shared plots and legends +## Shared plots and legends * If you have two side-by-side (left and right) figures (say, sub-figures) that have the same range in the vertical axis, you can remove the vertical labels on the one on the right and move it close to the one on the left so they are sharing the axis and tick labels. @@ -142,11 +120,12 @@ This principle is discussed more [here](https://bioinformatics-core-shared-train * Be specific with your legends. Your readers should be able to distinguish the data series by reading the legends only, not requiring the caption to determine what the figure means. -### Color bars +## Color bars If your data involves a color bar, use one that makes sense for the data you plot. You can read more about this online, like [here](https://chartio.com/learn/charts/how-to-choose-colors-data-visualization/) or [here](https://academy.datawrapper.de/article/140-what-to-consider-when-choosing-colors-for-data-visualization). -Common guidelines are +Common guidelines are + * Don't use the rainbow/jet color scheme (read more about the problem with this [here](https://stats.stackexchange.com/questions/223315/why-use-colormap-viridis-over-jet)) * Don't use a tri-color scheme (e.g., Paraview's default blue-white-red) for data that is not centered at a unique/special value like 0 * A violation would be using such a color scheme for data that varies from 0 to 1 @@ -155,13 +134,13 @@ Common guidelines are * Using a monochromatic color scheme (e.g., from white to black) for data that vary uniformly as above, say from 0 to 1. * Use a tri-color scheme that centers the color at black or white, e.g., the Paraview default red-white-blue for nominally centered data at a special or reference value, like 0 or 1. -### Coordinate direction arrow triad. +## Coordinate direction arrow triad. Do not show the coordinate direction arrows (usually x, y, z) included in Paraview and Visit exports by default. An exception might be creating a simulation video that requires the viewer to know these orientations. If you are exporting an image, superimpose your own direction triad if needed. -### Axis bounds and ticks +## Axis bounds and ticks Your axes should, whenever possible, start and end at labeled tick marks. This is especially important for log-scale axes. @@ -171,7 +150,7 @@ In pgfplots, this is achieved with the options: Avoid excessive text in tick marks when possible. For example, use `1, 2, 3, 4, 5` in units of `kHz` instead of `1000, 2000, 300, 4000, 5000` in units of `Hz`. -### Axis labels +## Axis labels In `tikz_preamble.tex`, the package `siunitx` is imported. If possible, use this to format your units. For example, if your units are in microseconds ($\mu \textrm{s}$), use `\unit{\micro\second}`. To access documentation on `siunitx`, visit [the package webpage here](https://ctan.org/pkg/siunitx?lang=en). @@ -186,11 +165,12 @@ For example, suppose you seek to indicate how your algorithm scales with the num "Number of Lattice Sites $N$" conveys this intention, albeit long, and simply using "Lattice Sites" is unclear. Someone unfamiliar with the content may interpret this as referring to data describing different points on a given lattice. -### Information quantity +## Information quantity Your figures should only contain the information required to tell the story or demonstrate the desired results. Examples of having too much information are, well, numerous. Some examples: + * You have too many tick marks * You include too many lines of data on your plot. @@ -206,12 +186,12 @@ Showing frivolous information distracts from your message. Avoid using colors that are too similar to the background to annotate figures. Use easily distinguishable colors. -### Consistency +## Consistency -Figures should also be consistent between each other and the surrounding text. -If you use a solid black line to denote the "exact solution" in one figure, do not switch to a dashed red line for a different exact solution in a later figure. -The fonts used in the figures should match the face and size of the surrounding text. -LaTeX uses Computer Modern and Latin Modern font faces and 11pt sizes by default, though journal templates and class files may change this. +Figures should also be consistent between each other and the surrounding text. +If you use a solid black line to denote the "exact solution" in one figure, do not switch to a dashed red line for a different exact solution in a later figure. +The fonts used in the figures should match the face and size of the surrounding text. +LaTeX uses Computer Modern and Latin Modern font faces and 11pt sizes by default, though journal templates and class files may change this. The font size of the captions below your figures should be one step smaller than that of your document (so 10pt if the document is nominally 11pt). The tick and axis labels should also be smaller than the nominal font size of your document; 9pt is usual here, and it should be consistently this size throughout your document. @@ -220,7 +200,7 @@ The tick and axis labels should also be smaller than the nominal font size of yo ```tex \includegraphics[width=0.3\textwidth]{figure.pdf} ``` -Doing so leads to inconsistent font sizes between the document and the software that generated the figure. +Doing so leads to inconsistent font sizes between the document and the software that generated the figure. __An exception__ to the above is if the figure contains no text or equations, like a simulation visualization. **Rule:** Use vector graphic formats (PDF, please) for all plots that involve text or equations. @@ -234,13 +214,13 @@ An excerpt from [Formatting your work](formatting.md). > From [here](https://www.annaclemens.com/blog/figure-graph-data-vizualisation-plot-scientific-paper): > A clear and consistent design in the figures in your scientific paper will make it easy for your reader to gather the presented information. For this, I suggest using the same color and symbols for each variable throughout all your scientific figures. Sample 1 is displayed as red triangles in Figure 1? Make sure it is in Figure 5, too. -### Useful references +## Useful references * [Principles of Beautiful Figures for Research Papers (must watch!)](https://www.youtube.com/watch?v=i-HAjex6VtM) * [Ten Simple Rules for Better Figures](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003833) * [How to make figures for scientific papers](https://www.annaclemens.com/blog/figure-graph-data-vizualisation-plot-scientific-paper) * [Brushing Up Science Figure Advice](https://brushingupscience.com/category/figures/) -### Additional Resources +## Additional Resources Additional resources on using Paraview and making presentable visualizations can be found [here](https://github.com/comp-physics/Scientific-Visualization) diff --git a/group-syllabus/formatting.md b/docs/group-syllabus/formatting.md similarity index 85% rename from group-syllabus/formatting.md rename to docs/group-syllabus/formatting.md index bda9c94..45c5a4d 100644 --- a/group-syllabus/formatting.md +++ b/docs/group-syllabus/formatting.md @@ -1,43 +1,21 @@ -## Formatting your documents +# Formatting your documents **Companion documents: [Improving your writing](improving-your-writing.md), [Making a figure](figures.md)** - - -## Table of Contents - -- [Why should I read this?](#why-should-i-read-this) -- [Consistency](#consistency) -- [Compiling and other boilerplate](#compiling-and-other-boilerplate) -- [Preamble and packages](#preamble-and-packages) -- [Units](#units) -- [Math symbols](#math-symbols) -- [Scientific notation and large/small numbers](#scientific-notation-and-largesmall-numbers) -- [Bibliography](#bibliography) -- [Referencing your bibliography](#referencing-your-bibliography) -- [Creating your bibliography](#creating-your-bibliography) -- [Colors](#colors) -- [Referencing equations, figures, tables, and sections](#referencing-equations-figures-tables-and-sections) - - [Figures, tables, sections](#figures-tables-sections) - - [Equations](#equations) -- ["Dashes"](#dashes) - - - -### Why should I read this? +## Why should I read this? For better or worse, the quality of your figures correlates with the perceived quality of your work. Just like the grammatical correctness of your writing, one might wonder if someone is sufficiently careful with their scientific work if they aren't very careful with their figures and presentation. I am putting some "rules" below for how to format your documents and figures. -### Consistency +## Consistency One should keep styles consistent within a manuscript. You might be forgiven for esoteric style choices if they are employed consistently. From [here](https://www.annaclemens.com/blog/figure-graph-data-vizualisation-plot-scientific-paper): -> A clear and consistent design in the figures in your scientific paper will make it easy for your reader to gather the presented information. For this, I suggest to use the same colour and symbols for each variable throughout all your scientific figures. Sample 1 is displayed as red triangles in Figure 1? Make sure it is in Figure 5 too. +> A clear and consistent design in the figures in your scientific paper will make it easy for your reader to gather the presented information. For this, I suggest to use the same colour and symbols for each variable throughout all your scientific figures. Sample 1 is displayed as red triangles in Figure 1? Make sure it is in Figure 5 too. -### Compiling and other boilerplate +## Compiling and other boilerplate * Use LaTeX for all of your documents. * Make sure your documents _do not_ compile with errors, especially if you are using Overleaf! @@ -45,7 +23,7 @@ From [here](https://www.annaclemens.com/blog/figure-graph-data-vizualisation-plo * On my local computer, I like using `latexmk` for compilation. * __Put each sentence on one line of source `.tex` code__ -### Preamble and packages +## Preamble and packages Always structure your document so that the preamble is separate from the main text (two separate files). You can connect them by placing `\input{preamble.tex}` at the top of your main text file `main.tex`, right after the @@ -55,10 +33,10 @@ You can connect them by placing `\input{preamble.tex}` at the top of your main t clause. In the preamble file, you should include some packages. -[Here](../templates/paper/preamble.tex) are some examples. +[Here](https://github.com/comp-physics/group-docs/blob/master/templates/paper/preamble.tex) are some examples. Please look them up to see what they do. -For `elsarticle` class files (mine is included [here](../templates/paper/elsarticle.cls)), which I recommend you use, you need to organize the hyper-reference coloring a bit differently, which in that example document you will see in the preamble as well the top of `main.tex` +For `elsarticle` class files (mine is included [here](https://github.com/comp-physics/group-docs/blob/master/templates/paper/elsarticle.cls)), which I recommend you use, you need to organize the hyper-reference coloring a bit differently, which in that example document you will see in the preamble as well the top of `main.tex` ```tex \documentclass[11pt,sort&compress]{elsarticle} @@ -77,7 +55,7 @@ For `elsarticle` class files (mine is included [here](../templates/paper/elsarti Discussion of these colors and their definitions are included below. -### Units +## Units Always use a LaTeX package if your quantities use units. My preference is @@ -94,25 +72,27 @@ Use proper package options: which configures the `siunitx` package to display units with division `m/s` using the slash symbol (/) instead of the reciprocal form `m s^{-1}`, amongst other things. See the template preamble for its use. -### Math symbols +## Math symbols Always use consistent math symbols. I usually put all of these in a single file that is invoked in the LaTeX preamble via ```tex \input{mathsymbols.tex} ``` -and an example such file is in `templates/paper/mathsymbols.tex` in this repository. +and an example such file is in [`templates/paper/mathsymbols.tex`](https://github.com/comp-physics/group-docs/blob/master/templates/paper/mathsymbols.tex) in this repository. Some notation rules you should follow + * Bold lowercase for vectors * Bold uppercase for matrices and tensors * Non-bold lowercase for scalars/constants Common errors + * Dimensionless symbols like the Reynolds number __should not__ be italic, but upright. * Like this $\mathrm{Re}$ * Not like this $Re$ -* Super and subscripts that denote text __should not__ be in math/italic symbols but rather upright normal text. +* Super and subscripts that denote text __should not__ be in math/italic symbols but rather upright normal text. * Like this: $c_{\mathrm{Temp.}}$ or $\mathbf{A}_{\mathrm{Fast}}$ * This is also OK: $c^{\mathrm{(Temp.)}}$ or $\mathbf{A}^{\mathrm{(Fast)}}$ * But not like this: $c_{Temp}$ or $\mathbf{A}_{Fast}$ @@ -127,20 +107,21 @@ Common errors * Do this: $\left(1 + a\left(1+ \frac{a + b}{b} \right) \right)$ * Note that in the incorrect version, the closing parenthesis is too small and does not scale to the height of the fraction -### Scientific notation and large/small numbers +## Scientific notation and large/small numbers __Rule:__ Never use the notation $4e-5$, $4e+05$, or the like in any paper, presentation, or figure. Always use $4 \times 10^{-5}$. If units are involved, use `siunitx` and the options listed in the paper template `preamble.tex`. -### Bibliography +## Bibliography Always use consistent formatting. This might mean more than it seems at first. Some examples and common errors: -* Choose to either abbreviate journal names (using the __correct__ abbreviation, Google it!) or use the full journal name (use camel case! _Journal of Fluid Mechanics_ __not__ _Journal of fluid mechanics_), then stick with it. - * Like this (full names): + +* Choose to either abbreviate journal names (using the __correct__ abbreviation, Google it!) or use the full journal name (use camel case! _Journal of Fluid Mechanics_ __not__ _Journal of fluid mechanics_), then stick with it. + * Like this (full names): * Firouznia, M., Bryngelson, S. H., Saintillan, D. (2023). A spectral boundary integral method for simulating electrohydrodynamic flows in viscous drops. Journal of Computational Physics, 489, 112248. * Spratt, J.-S., Rodriguez, M., Schmidmayer, K., Bryngelson, S. H., Yang, J., Franck, C., and Colonius, T. (2021). Characterizing viscoelastic materials via ensemble-based data assimilation of bubble collapse observations. Journal of the Mechanics and Physics of Solids, 152, 104455. * Or like this (abbreviations) @@ -170,13 +151,13 @@ Some examples and common errors: * M. A. Nielsen and I. L. Chuang, _Quantum Computation and Quantum Information_ (Cambridge University Press, 2000) * T. Kruger, H. Kusumaatmaja, A. Kuzmin, O. Shardt, G. Silva, and E. Viggen, _The lattice Boltzmann method: Principles and practice_ (Springer International Publishing, 2016) -### Referencing your bibliography +## Referencing your bibliography Use `natbib` via `\usepackage{natbib}` (it is automatically loaded when one uses the `elsarticle` class). -I recommend the bibliography style file in the template at `templates/paper/bibsty.bst`. +I recommend the bibliography style file in the template at [`templates/paper/bibsty.bst`](https://github.com/comp-physics/group-docs/blob/master/templates/paper/bibsty.bst). This is automatically handled if you use the paper template in this repository. This way, you will have access to text and parenthetical citations, which render as: -> One can partially address this problem by working in Fourier space [1] or fitting a parametric model to approximate the eddy diffusivity operator [21, 23]. However, the former requires spatial homogeneity, and the latter's accuracy depends on the parametric model's quality. Liu et al. [17] introduces an improved model that uses the nonlocal eddy diffusivity operator's moments to approximate the operator. +> One can partially address this problem by working in Fourier space [1] or fitting a parametric model to approximate the eddy diffusivity operator [21, 23]. However, the former requires spatial homogeneity, and the latter's accuracy depends on the parametric model's quality. Liu et al. [17] introduces an improved model that uses the nonlocal eddy diffusivity operator's moments to approximate the operator. via the code ```tex One can partially address this problem by working in Fourier space or fitting a parametric model to approximate the eddy diffusivity operator~\citep{hamba04,park21}. @@ -185,6 +166,7 @@ However, the former requires spatial homogeneity, and the latter's accuracy depe ``` __Note__ the use of `\citep{ref}` and `\citet{ref}` here. Text `\citet{ref}` instances can be used as nouns but parenthetical references _cannot_. + * This is OK (via `\citet{ref}`): > So and so [1] did this awesome thing. * This is not (via `\citep{ref}`): @@ -192,10 +174,12 @@ Text `\citet{ref}` instances can be used as nouns but parenthetical references _ Always prevent line-breaks via tides `~` between a parenthetical reference and the text before it. For example: + * This is correct: `The algorithm is fast, but not as fast as possible~\citep{ref}.` * This is not: `The algorithm is fast, but not as fast as possible \citep{ref}.` We generally want our references at the end of sentences unless they are part of a long list. + * Incorrect: > The LBM method [1] is not as accurate as the finite volume method [2]. * Correct: @@ -203,12 +187,12 @@ We generally want our references at the end of sentences unless they are part of * And this is also acceptable > Cavitation is seen in many engineering applications, including submarines [1], pumps [2], and medical devices [3]. -### Creating your bibliography +## Creating your bibliography * Use `bibtool` to remove unused entries from your bibliography (`.bib`) file - * Remove all unused bibliography entries from your `.bib` file. To do this, + * Remove all unused bibliography entries from your `.bib` file. To do this, * Make sure you have `bibtool` installed your your system - * Copy a `bibtool.config` file to your document path, mine is located [here](../templates/paper/bibtool.config) + * Copy a `bibtool.config` file to your document path, mine is located [here](https://github.com/comp-physics/group-docs/blob/master/templates/paper/bibtool.config) * Compile your document (I prefer `latexmk` for this, but a combination of `pdflatex` and `bibtex` also works). * Use the command `bibtool -r bibtool.config -x main.aux > test.bib` * Now you have a file `test.bib` that contains only the bibliography entries in your document @@ -219,10 +203,10 @@ We generally want our references at the end of sentences unless they are part of * You can see above that it removes certain entries, sorts the document, checks for duplicates, etc. * It does this on `test.bib` in the above call. You will want to do it on whatever the `bibtool` output file is. -* Bibliography style file (`.bst`) - * Unless the journal or conference you submit to insists otherwise, use the style file [here](../templates/paper/bibsty.bst). This style file includes the relevant information you want your entries to include (like title), but ignores others (like month of publication). It also supports author-year citations (invoked via `\citet{}` as above). +* Bibliography style file (`.bst`) + * Unless the journal or conference you submit to insists otherwise, use the style file [here](https://github.com/comp-physics/group-docs/blob/master/templates/paper/bibsty.bst). This style file includes the relevant information you want your entries to include (like title), but ignores others (like month of publication). It also supports author-year citations (invoked via `\citet{}` as above). -### Colors +## Colors I like to use the following color palette in your TeX preamble: ```tex @@ -249,9 +233,9 @@ Setup your hyperrefs this way so that you have an attractive notation of your cr \usepackage[colorlinks=true,linkcolor=darkrust,citecolor=darklightblue,urlcolor=darksilver]{hyperref} ``` -### Referencing equations, figures, tables, and sections +## Referencing equations, figures, tables, and sections -#### Figures, tables, sections +### Figures, tables, sections To keep things consistent, I recommend using the `cleveref` package ```tex @@ -261,7 +245,7 @@ which is invoked for figures, tables, and sections via the commands `\Cref{}` an Figures, tables, and sections are always treated as nouns. Check out the paper template in this repository for its use in the `preamble.tex` file. -#### Equations +### Equations First, labeling them appropriately as ```tex @@ -273,21 +257,24 @@ First, labeling them appropriately as and then reference then via `cleveref`! As `\cref{e:lineareqn}`. Treat your equations as nouns, and never use the abbreviation "eqn." before it. + * Like this: `The algorithm follows from reducing \eqref{e:someqn} to a first-order system.` - * Which renders as: + * Which renders as: > The algorithm follows from reducing (1) to a first-order system. * Not like this: `The algorithm follows from reducing equation \eqref{e:someqn} to a first-order system.` * Nor like this: `The algorithm follows from reducing eqn. \eqref{e:someqn} to a first-order system.` -### "Dashes" +## "Dashes" Learn the difference between the hyphen (`-` in LaTeX), the en dash (`--` in LaTeX), and the em dash (`---` in LaTeX). This is easily Google-able. Here are some references: + * https://grammarist.com/usage/hyphen-en-dash-or-em-dash/ * https://www.grammarly.com/blog/hyphens-and-dashes/ * https://editorninja.com/hyphen-vs-en-dash-vs-em-dash/ Some correct examples + * Hyphen * Separating words, such as "over-subscribed". * Some last names @@ -297,5 +284,3 @@ Some correct examples * Em dash * For putting a parenthetical in a sentence, like "I went to the grocery store---one that was extremely far away---and picked up cooking supplies." * I recommend avoiding the use of the em dash. - - diff --git a/group-syllabus/funding.md b/docs/group-syllabus/funding.md similarity index 82% rename from group-syllabus/funding.md rename to docs/group-syllabus/funding.md index 8712136..319d404 100644 --- a/group-syllabus/funding.md +++ b/docs/group-syllabus/funding.md @@ -1,15 +1,5 @@ - - -## Table of Contents -- [Funding](#funding) - - [Research and Teaching Assistantship](#research-and-teaching-assistantship) - - [Fellowships](#fellowships) - - [Stipend](#stipend) - - - -## Funding +# Funding If you are an undergraduate, [click here](undergraduate-specifics.md). @@ -17,7 +7,7 @@ Your Ph.D. comes with guaranteed funding (i.e., stipend, tuition, health insuran This means you are guaranteed to have a fellowship, Graduate Research Assistantship (RA), or Teaching Assistantship (TA) to support you throughout your time at Georgia Tech. You also do not pay to attend conferences, this is covered via research funds. -### Research and Teaching Assistantship +## Research and Teaching Assistantship It is my role to make sure that you are supported by an RA, TA, or fellowship for as much of your Ph.D. as possible. Your Ph.D. program will require some (typically two) semesters of TA during your Ph.D., though you could be asked to do more of them. @@ -26,11 +16,11 @@ RAs generally means some sort of grant or research award supports your work. Again, it is my role to raise this money to support your research, or to fit your research into funding that I already have. It is also possible that later in the Ph.D. I will ask you (or you will initiate) for your help in writing a grant proposal in your area. This is good practice for you as a future scientist. - + TAs represent a certain, bounded amount of work in terms of hours per week. Your Ph.D. work should be filling the rest of your working hours. -### Fellowships +## Fellowships I expect you to apply for appropriate fellowships during your Ph.D. Some have restrictions on citizenship or permanent residency, so you may not be eligible for all of them. @@ -39,10 +29,9 @@ Such fellowships include ones from federal agencies, like the NSF GRFP, the DOD Usually, these applications are not too much work, and as a side benefit require you to articulate your research vision and interests. When you get one, everyone benefits: you are more flexible in your work to pursue your research direction without the pull of funding needs; I spend more time with you and less time getting grants; and you get a recognition that goes on your CV. Not a bad situation to be in. - -### Stipend + +## Stipend Your stipend is determined by the Graduate School at Georgia Tech. The Ph.D. stipend is by no means a lot of money, but I believe people have found that it supports a comfortable life that allows you to focus on your studies. On a related note, there is an expectation that your Ph.D. will be your full-time work, though internships, particularly during the summer, are possible and sometimes recommended. - diff --git a/group-syllabus/giving-talks.md b/docs/group-syllabus/giving-talks.md similarity index 89% rename from group-syllabus/giving-talks.md rename to docs/group-syllabus/giving-talks.md index 1c83980..400ec50 100644 --- a/group-syllabus/giving-talks.md +++ b/docs/group-syllabus/giving-talks.md @@ -1,25 +1,13 @@ -## Giving and attending talks +# Giving and attending talks Talks are important: They show your command of your research and your ability to stitch together a story worth listening to. Most professors will agree that the new faculty hired into the school are judged primarily on their job talk. - - -## Table of Contents - -- [What are you trying to achieve?](#what-are-you-trying-to-achieve) -- [How to](#how-to) -- [Feedback](#feedback) -- [Q&A](#qa) - - [If you are answering the questions (you're the speaker)](#if-you-are-answering-the-questions-youre-the-speaker) - - [If you are asking the questions (you're in the audience)](#if-you-are-asking-the-questions-youre-in-the-audience) - - - -### What are you trying to achieve? +## What are you trying to achieve? Giving a talk is presumably associated with some goals, otherwise, why give it? You should organize your talk to achieve these goals. Here are some examples of things you might want people to think after your talk: + * I saw a nice talk about X from this person Y at Georgia Tech. We should look more into what they're up to (or talk to them after the talk) * This talk was about X and the main results were Y. (You will find many talks do not meet this seemingly low bar) * This work was about X and I'm also working in X! They're doing Y and we're doing Z. Maybe we can collaborate and improve X together. @@ -27,7 +15,7 @@ Here are some examples of things you might want people to think after your talk: All of the above are very real things, and I've thought about each of them several times before. -### How to +## How to The guidance I usually give around talks is somewhat traditional: plan, make, and practice. @@ -37,7 +25,7 @@ From that number, I break down how much time I want to spend on the different pa 2. __Build:__ After the above, I start building slides. Use the group template, which is available in this repository. Acknowledge the sponsor of your research on the last slide or two, depending on how the slides are arranged. -3. __Practice:__ After you have your slides, practice the talk by yourself: Pull up your slides and start going through the talk aloud on your laptop with no one else around. +3. __Practice:__ After you have your slides, practice the talk by yourself: Pull up your slides and start going through the talk aloud on your laptop with no one else around. Fortunately, the talks you're likely to give early in your academic career are also the shortest. This means you can practice them, in their entirety, a dozen times within an hour or two. I guarantee that a talk practiced front-to-back 12 times will be delivered more cleanly than one never practiced, and everyone in the room can tell the difference. @@ -49,24 +37,25 @@ After you synthesize and iterate on all the feedback, you're ready to go. This process often takes many days, even for a short talk. _This means that you should be ready to start practicing at least one week before you give your talk._ -### Feedback +## Feedback The most common feedback I give for talks is: + * No "table of contents" for short talks (15 minutes or less) * This just wastes otherwise valuable time -* The talk was not structured for the audience. +* The talk was not structured for the audience. * Who are you talking to? It matters! In fact, it might be the thing that matters most. -* What was your message? +* What was your message? * If the message is unclear to me, it will definitely be unclear to others. If your talk doesn't have a message, consider why, come up with an appropriate one, and restructure your slides. -* You did not practice enough. - * You know your talk is well practiced when you can deliver it without looking at the slides/projector most of the time. Why? Because you already know what's on them, and what's coming next! This allows you to engage with the audience. +* You did not practice enough. + * You know your talk is well practiced when you can deliver it without looking at the slides/projector most of the time. Why? Because you already know what's on them, and what's coming next! This allows you to engage with the audience. * You know your talk is not well-practiced when you are reading the slides: I, too, can read your slides. If that's what you were going to do, you could have just sent a PDF of the slides to the audience to peruse at their own leisure. * Stop using superlatives. - * Words like _very_ can pollute an otherwise excellent talk. "The relationship is _very_ complicated." "This equation is _very_ nonlinear." What does one intend with such words? + * Words like _very_ can pollute an otherwise excellent talk. "The relationship is _very_ complicated." "This equation is _very_ nonlinear." What does one intend with such words? * You use many filler words. * Avoid using "umm" or "uhh". You will likely be guilty of this to some degree until the day you graduate, but you will be better than when you started working on research. I am guilty myself, that's for sure. I think the best remedies are @@ -74,7 +63,7 @@ The most common feedback I give for talks is: 2. Practicing 3. Having someone tell you when you do this. * Don't let the first words out of your mouth be your talk title, verbatim - * You will almost always have someone introduce you and your talk. They will almost surely recite your talk title during this. Don't start your talk by repeating what the introducer/session chair just said, it suggests you are reciting your talk from some kind of script. + * You will almost always have someone introduce you and your talk. They will almost surely recite your talk title during this. Don't start your talk by repeating what the introducer/session chair just said, it suggests you are reciting your talk from some kind of script. * An above example of what not to do looks something like: * __Introducer:__ "We are pleased to have Mr/s. X giving a talk! They will be talking about _"your talk title here"_. * __You:__ "Thanks for having me! Today I am going to be talking about _"your talk title here"_. @@ -82,22 +71,22 @@ The most common feedback I give for talks is: * There is too much text on your slides. * Figure out what your message is and then remove text and speech that does not help deliver this message. Here is a simple example. * __Example:__ You list, to five decimal places, the coefficients of the stiffened gas equation of state you used to model the properties of water. - * __Problem:__ No one cares and they assume you are sufficiently competent to use reasonable ones. If your results are sensitive to this information then you would most certainly be giving a very different talk indeed. + * __Problem:__ No one cares and they assume you are sufficiently competent to use reasonable ones. If your results are sensitive to this information then you would most certainly be giving a very different talk indeed. * The point: This is not a journal article, and not _everything_ needs to be explicitly stated or referenced. Only the things that contribute to your story. * I can't hear you. - * This isn't usually technically true, my hearing is pretty good, but I recommend you project your voice into the room and speak clearly. Not doing this is one sure way to lose the attention of the audience. + * This isn't usually technically true, my hearing is pretty good, but I recommend you project your voice into the room and speak clearly. Not doing this is one sure way to lose the attention of the audience. * Example: Many times we acknowledge that we could barely understand what a speaker was saying. Rarely do we say "man, they were way too loud, that was obnoxious." * It can sometimes be hard to judge if you are speaking too quietly. One way to know for sure is having someone tell you, which I will do. Another reason students speak quietly or are simply unclear is because they are nervous, bringing me to... * Nervous about public speaking? You are in good company, [77% of the US population feels the same.](https://orai.com/blog/fear-of-public-speaking-statistics/) This isn't to undermine the issue, but support it. The best therapy is likely [exposure therapy](https://www.apa.org/ptsd-guideline/patients-and-families/exposure-therapy). This is, in part, why you will stand up to give your group updates each week, give practice talks, and give low-stakes talks at various departmental/student seminars. If you struggle with anxiety, [consider](https://www.apa.org/ptsd-guideline/patients-and-families/seeking-therapy) seeking a mental health specialist. -### Q&A +## Q&A After a talk, there will usually be a Q&A period. I like to think of it as discussing with a colleague, just in front of a large audience. That's the tone I'm aiming for in my questions and answers. -#### If you are answering the questions (you're the speaker) +### If you are answering the questions (you're the speaker) 1. Remember that you almost certainly know more about the details of your work, especially the very specific work you conducted, than anyone else in the room. @@ -121,7 +110,7 @@ I have done this many times during Q&A, and there is nothing embarrassing about 6. Wait until the questioner is done asking the question before you start answering. -#### If you are asking the questions (you're in the audience) +### If you are asking the questions (you're in the audience) 1. Do not ask "questions" that do not end in question marks. Use Q&A to learn or clarify something. diff --git a/group-syllabus/going-to-conferences.md b/docs/group-syllabus/going-to-conferences.md similarity index 87% rename from group-syllabus/going-to-conferences.md rename to docs/group-syllabus/going-to-conferences.md index 0d1dfb0..0329159 100644 --- a/group-syllabus/going-to-conferences.md +++ b/docs/group-syllabus/going-to-conferences.md @@ -1,26 +1,12 @@ - - -## Table of Contents -- [Submitting and going to conferences](#submitting-and-going-to-conferences) - - [What's the point, anyway?](#whats-the-point-anyway) - - [Am I going?!](#am-i-going) - - [Can I go to observe? (without a paper or abstract)](#can-i-go-to-observe-without-a-paper-or-abstract) - - [Registration, flights, and hotels](#registration-flights-and-hotels) - - [Spend authorization](#spend-authorization) - - [Actually going to the conference](#actually-going-to-the-conference) - - - -## Submitting and going to conferences +# Submitting and going to conferences __Related documents: [Giving talks](giving-talks.md)__ - Most of this goes for undergraduates and graduate students alike. The "spend authorization" part is only for graduate students. -### What's the point, anyway? +## What's the point, anyway? Often, in our field, conferences are _not a major_ way to establish impact in a field (as opposed to machine learning, for example); there are some exceptions (SC papers are one). Instead, conferences are a way to learn and talk with colleagues about research. @@ -28,7 +14,7 @@ For newer students, it is a way to see how the research community operates as we If you and I both go, I will try to introduce you to people relevant to your work. If you go alone, I can give you some folks to "hunt down" while you are there, as they might be familiar with our work. -### Am I going?! +## Am I going?! You may be the lead author on a conference abstract or "short paper" but not attend the conference. Sometimes, you will attend the conference, but I will not. @@ -39,7 +25,7 @@ I try to convey these things as quickly as possible, especially if you are going But, sometimes, I get quite busy, and things fall through the cracks. If you do not know what's going on, I encourage you to ask me! -### Can I go to observe? (without a paper or abstract) +## Can I go to observe? (without a paper or abstract) Sometimes, students go to conferences to "observe." They do not have a talk to give or an abstract or poster to present. @@ -48,7 +34,7 @@ However, this can be extremely expensive (more than you might realize). This can also hinder my ability to later send you to more conferences where you _will_ have papers to present. As a result, I do not support "observation" conference attendance with my own research funds, though sometimes you can win a conference attendance grant (these are conference-specific, and PURA Travel is not sufficient for undergraduate researchers). -### Registration, flights, and hotels +## Registration, flights, and hotels I cover all of your conference costs via grant funds. As such, you will not incur any personal costs for attending a conference, including registration, flight, hotel, and meals. @@ -63,26 +49,28 @@ We know we are attending conferences many months in advance, so there is little * Per diem: You will be reimbursed for your meals via the per diem rate for the conference location. -### Spend authorization +## Spend authorization If you are a graduate student employee (on a GRA: Graduate Research Assistantship), you need a spend authorization to be approved by Georgia Tech before going to a conference. To file a spend authorization, go to [Workday](https://wd5.myworkday.com/gatech/d/home.htmld), log in with your GT credentials, and type `Create Spend Authorization` in the search bar at the top of the page. This should take you to a web form to fill out. An example of how to fill this out + * Start Date: A day before you leave for the conference * End Date: The day after you return from the conference * Description: Travel to attend and give a talk at X conference -* Business Purpose: Conference/seminar (should autofill) +* Business Purpose: Conference/seminar (should autofill) Click `Add` under `Spend Authorization Lines` + * Expense item: `Miscellaneous - Domestic` or `Miscellaneous - International` (depending on if international or not) * Total amount: about 20% more than your actual planned expenses * Grant: I will give you a number to copy-paste into here, then link 'Enter,' and it should auto-populate most other fields. That's it! Ask your colleagues if you have questions, and ask me if they don't know the answer. -### Actually going to the conference +## Actually going to the conference Once you have identified the conference you want to attend, the next steps are: diff --git a/group-syllabus/hardware.md b/docs/group-syllabus/hardware.md similarity index 82% rename from group-syllabus/hardware.md rename to docs/group-syllabus/hardware.md index 4280867..ea37b71 100644 --- a/group-syllabus/hardware.md +++ b/docs/group-syllabus/hardware.md @@ -1,12 +1,5 @@ - - -## Table of Contents -- [Whose hardware is this, anyway?](#whose-hardware-is-this-anyway) - - - -## Whose hardware is this, anyway? +# Whose hardware is this, anyway? During your Ph.D. or, sometimes, undergraduate work, you will acquire hardware that appears to be "from me" to assist with your research. This hardware is funded by a grant or some other money issued to my research program through the institute. @@ -20,4 +13,4 @@ If you feel uncomfortable being responsible for hardware, like a laptop, that yo __Note:__ This does __not__ mean that if something happens to your laptop or other hardware, you are personally responsible (nor will I be upset)! Such things happen, and over the course of a Ph.D., they are not entirely unlikely. Your responsibility is quite simple and hopefully easy to abide by: do not intentionally modify or abuse the hardware, and the overarching point of the document is clarification of ownership (which is often not obvious to students). -__Aside:__ At time of writing, I only purchase MacBooks for myself and student researchers. There are several reasons for this. Some examples that come to mind are MacOS being UNIX-based with strong software adoption (from native builds of linear algebra libraries to the MS Office suite) and Apple laptops having high quality standards, long battery life, and reliable use for presentations. +__Aside:__ At time of writing, I only purchase MacBooks for myself and student researchers. There are several reasons for this. Some examples that come to mind are MacOS being UNIX-based with strong software adoption (from native builds of linear algebra libraries to the MS Office suite) and Apple laptops having high quality standards, long battery life, and reliable use for presentations. diff --git a/group-syllabus/improving-your-writing.md b/docs/group-syllabus/improving-your-writing.md similarity index 88% rename from group-syllabus/improving-your-writing.md rename to docs/group-syllabus/improving-your-writing.md index d2073e6..a17ef90 100644 --- a/group-syllabus/improving-your-writing.md +++ b/docs/group-syllabus/improving-your-writing.md @@ -1,251 +1,232 @@ -## Academic writing - -**Companion documents: [Formatting your work](formatting.md), [Improving your writing](improving-your-writing.md), [Making a figure](figures.md), [Responding to reviewers](responding-to-reviewers.md)** - - - -## Table of Contents - -- [Why should I read this?](#why-should-i-read-this) -- [Automatic grammar, spelling, and syntax checkers](#automatic-grammar-spelling-and-syntax-checkers) -- [Consistency](#consistency) -- [Nomenclature](#nomenclature) -- [Variable Naming](#variable-naming) -- [Concise writing](#concise-writing) -- [What goes where](#what-goes-where) -- [Guidelines, tips, and more!](#guidelines-tips-and-more) - - [Things to avoid; from the Angry Reviewer](#things-to-avoid-from-the-angry-reviewer) - - [From some tips for scientific writing](#from-some-tips-for-scientific-writing) - - [From Koen Hufkens](#from-koen-hufkens) -- [Required watching](#required-watching) -- [Other links](#other-links) - - - -### Why should I read this? - -Many students have trouble producing scientifically acceptable writing without significant training. -(I use "scientifically acceptable" as a suitcase word for whatever seasoned academics find appropriate in journal papers.) -Perhaps this isn't surprising; students do not formally learn how to do this. - -This difficulty is juxtaposed with just how important your writing is. -You likely will only remember some details of your past research projects. -Instead, you'll be able to use your papers as references. -Other scientists won't see your research notes (nor would you want them to) or know the details of your academic past. -Instead, they will judge you based on your archived writing (conference proceedings and journal articles). -Only a few opportunities exist to side-step this. -Giving conference and invited talks communicates your research without paper-in-hand. -However, this format is ephemeral. -Anyone interested in your talks can find your papers to understand your contributions without time constraints. -It is also two-way coupled: you will likely only be invited to give talks with the presumption of good papers behind them. - -Careful writing also begets careful thinking (and vice-versa). -That is, forcing yourself to clarify and organize your work will bring problems in your thinking to light. -Because of this, improving your writing as soon as possible can be useful. -New students may well be over a year from starting a manuscript for a journal. -However, they, too, will benefit from carefully writing up their notes, ideas, and plans. - -For the above reasons, high-quality scientific writing is often expected from students ready to graduate with their Ph.D. -I invite you to use this document to bootstrap your way to scientifically-acceptable technical writing. - -From a now-deleted StackExchange post on "pet peeves in academic writing": -> Ernest Hemingway wrote, "the only kind of writing is rewriting." E. B. White wrote essentially the same thing: "The best writing is rewriting." -> -> I have plenty of pet peeves about academic writing, but they all seem to have the same cause: that the author apparently didn't care about writing well. -> -> Your first version of anything is likely to be mediocre. (That's certainly true for me!) Care about your own writing, enough to notice and be annoyed by shortcomings in your first draft, and then figure out how to improve it. Do this, and you will be well on your way to excellent writing. - -Also see: [Does writing matter a lot in research?](https://academia.stackexchange.com/questions/107919/does-writing-matter-a-lot-in-research) - -### Automatic grammar, spelling, and syntax checkers - -Several of these exist. -I use [Grammarly](https://www.grammarly.com/). -It offers a free tier and a trial of the "pro" service at the time of writing. -I purchased the full Grammarly and do not regret the purchase. -The [Angry Reviewer](https://www.angryreviewer.com/) tool is also helpful for giving line-by-line feedback. -A general list of rules used in this tool is available [here](https://www.angryreviewer.com/rules). -We elaborate on this below. - -These tools can check for simple things, like improper spelling and grammar. -They can also identify more complicated style-related things, such as active and passive voices, repeated words and sentence-starters, "sticky sentences" (run-on sentences held together by many articles), and so on. - -I recommend using one of these before submitting any paper or abstract. -Often, even seemingly obvious mistakes can go unnoticed after so many revisions. -Such mistakes are a quick way for an editor or reviewer to perceive your work as careless (e.g., does he conduct his simulations like he writes his abstracts?!), even if only subconsciously. - -### Consistency - -One should keep styles consistent within a manuscript. -You might be forgiven for even poor style choices if you are consistent. -Please look at the [these](formatting.md) documents for more. -Note that this consistency extends to the level of detail throughout the paper. -A detailed introduction is best matched with a results section that achieves a similar level of detail. - -### Nomenclature - -Changing technical terms mid-way through a paper in the name of style will confuse people. -If your domain is a cylinder, don't switch to "tube" at any point. -If you call your model a "physical model," do not switch to calling it a "numerical model" (with the additional problem that these two things aren't the same, anyway). -If you define your "mesh spacing" in one section, don't switch to "grid spacing" or "mesh resolution" later on. -Don't use software-specific nomenclature. -This confuses readers if they haven't used the software, and they may not plan to use it. - -### Variable Naming - -Names of variables should make sense for an outside reader. -The objective is to make the paper as easily readable as possible. -In some cases, there may be a standard variable used for the value. -For example, consider how $c$ is used to denote the speed of sound. -Using $m$ to denote the speed of sound is not invalid, but may be confusing at the outset. - -Beware of using too many distinct variables for quantities, especially related ones. -This leads to confusion for the reader, who now must keep track of a variable table on top of the content of the work. -Make use of subscripts to annotate the variable and simplify the naming scheme. -For example, suppose we have the following values to be used in equations: -- Number of samples -- Number of lattice sites -- Number of dimensions - -We may use $M$, $N$, and $K$ to denote each of these quantities. -However, this is confusing and fails to show that we are simply counting the "number of [something]". -Instead, denote the values using variables $N_{samp.}$, $N_{sites}$, and $N_{dim.}$. - -### Concise writing - -One should prefer using as few words as required when describing something technical. -You can consult replacement lists for common mistakes: - -* [Wordy phrases](https://grammarist.com/wordiness/) -* [Wordy phrase replacements](https://www.kingcounty.gov/help/editorial-style-guide/concisewriting/wordyphrases.aspx) -* [Wordiness, Wordiness, Wordiness List](https://web.uvic.ca/~gkblank/wordiness.html) -* [50 Plain-Language Substitutions for Wordy Phrases](https://www.dailywritingtips.com/50-plain-language-substitutions-for-wordy-phrases/) - -These lists help me realize, "Hey, I write wordy phrases like this all the time!" -Use the lists to learn the general ways one ends up with low information-density writing. -You can then identify similar phrases in your writing. -Often, eliminating them is relatively easy, but noticing them is (at first). - -Conciseness can be viewed in a broader sense. -For example, you should structure your paragraphs such that you aren't repeating information. -Other tips of this type are available at these links: - -* [Writing Concisely – The Writing Center • University of North Carolina at Chapel Hill](https://writingcenter.unc.edu/tips-and-tools/conciseness-handout/) -* [Writing Clearly & Concisely](https://writingcenter.ashford.edu/writing-clearly-concisely) -* [Tips for being concise in academic writing](https://lauraripperproofreading.com/2018/01/26/how-to-be-concise-tips-for-academic-writing/) - -### What goes where - -__Always__ have a narrative first figure demonstrating what you are doing and "telling the overall story." -Take time to make this figure as attractive as possible. -It is one of the first things your readers will see! -See, for example, the first figure in my paper, "Fast Macroscopic Forcing Method." - -* Abstract - * Include a full, self-contained mini-version of your paper, including an introduction to your method, quantitative measures of your results, and conclusion and takeaways. -* Introduction (in this order) - * What is your work? - * Why are you doing it? - * What is the open problem you are trying to solve? - * What are some methods related to your work? - * What key contributions will you add? (without full detail) - * What does the rest of the manuscript contain? -* Acknowledgments - * We always have an unnumbered acknowledgment section before the references but after the discussion/conclusions. This is where we acknowledge funders and those who have helped with the work but are not authors. -* Future work - * I recommend not including a future work section in your papers or presentations - -### Guidelines, tips, and more! - -#### Things to avoid; from the [Angry Reviewer](https://www.angryreviewer.com/rules) - -* Don't hype. Avoid words like novel, highly, clearly, greatly. Better still, avoid all adverbs. -* Don't use clichés. In a nutshell, by and large, they are clear as mud. -* Don't use "very" very often. Usually, there is a better word for it. -* Be concise. Avoid phrases like "by means of, despite the fact that, in order to". -* Avoid negatives. For example, use "unable" instead of "not able". -* Avoid redundancy. For example, use "investigate" instead of "conduct an investigation of". -* Use active voice. Although not always possible, most text should be in an active voice. -* Avoid inappropriate language. Keep words like "really, actually, pretty much" for social networks. -* Avoid rare words and latinisms. Non credo all readers know the meaning. -* Keep abbreviations to a minimum. Abbreviations are hard to read, consider just spelling it out. -* Beware of zombie nouns. Utilization of nominalization is the causation of distraction. - -#### From [some tips for scientific writing](https://kucharski.substack.com/p/some-tips-for-scientific-writing) - -* Use the "show, don't tell" technique. If something is interesting or surprising, the reader should be interested or surprised by what they've read. They shouldn't need to be told. Anton Chekhov reportedly said: "Don't tell me the moon is shining; show me the glint of light on broken glass." - -* Don't bury the lede. When journalists write articles, they usually include crucial information in the opening paragraph. Hiding big news later in the piece is known as "burying the lede." This idiom forms part of the inverted pyramid approach to writing: put the most important information first in an article or section, then fill out the details. - -* Read widely, reflecting as you go. Why was that sentence hard to follow? Why did you like that section of text? Why was that turn of phrase annoying? What gave that paragraph its nice balance and rhythm? As Toni Morrison once put it: "Writing is a way of thinking – not just feeling but thinking about things that are disparate, unresolved, mysterious, problematic or just sweet." - -* Make your readers care about what they're reading. Like a good story, this typically means outlining a clear problem and promising a later resolution. - -* Some anonymous entities didn't do the analysis. You did the analysis. So avoid the passive voice if possible. (See also: "a decision was made" rather than "we made the decision" when it comes to responsibility-dodging in leadership messages.) - -* If you promise something in the introduction, ensure you've delivered by the end of the results. For example, if you open by mentioning A and B, readers will be expecting a conclusion about A and B by the end of the paper. "Remove everything that has no relevance to the story,' as Chekhov put it. "If you say in the first chapter that there is a rifle hanging on the wall, in the second or third chapter, it absolutely must go off." - -* Follow Orwell's rules of writing - * Never use a metaphor, simile, or other figure of speech that you are used to seeing in print. - * Never use a long word where a short one will do. - If it is possible to cut a word out, always cut it out. - * Never use the passive where you can use the active. - * Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. - * Break any of these rules sooner than say anything outright barbarous. - -* Kill your darlings. Sometimes, you'll write a so elegant and well-crafted phrase that it jars with the rest of your writing and pulls the reader out of the flow. So cut it. As Stephen King once put it: _'Kill your darlings, kill your darlings, even when it breaks your egocentric little scribbler's heart, kill your darlings.'_ - -* If you want to describe a figure/table in the results text, it can help to imagine you're giving a seminar. What features would you draw your audience's attention to? What would you tell people about during coffee break? - -* Help the reader interpret your figures and tables. Don't give them a sixteen-panel graph and expect them to spot the main takeaway; if the author can't be bothered to find a key message, the reader almost certainly won't either. - -* You can probably cut your word count by about half if you need to, without losing meaning. (I've managed to cut down a bunch of paper submissions into much shorter report formats when pressed.) - -* A good intro and discussion will often include a reference or statistic most readers won't have been aware of. Try and find the best references, rather than the easiest ones. - -#### From [Koen Hufkens](https://github.com/khufkens/paper_writing_checklist) - -His document covers a small subset of components of a well-written manuscript. -Some of these are soft writing rules/guidelines. -They can be broken, but before breaking them, one usually has to understand why they exist. -If you consciously break a rule in your view for a good reason, then go for it. -Otherwise, stick to the guidelines. - -- [ ] Use active language -- [ ] Avoid long sentences -- [ ] Simplify your language (_no thesaurus_) -- [ ] One paragraph communicates one important idea -- [ ] Connect paragraphs and ideas in a logical order -- [ ] Use the present tense for the main part of the manuscript; past tense is allowed in some parts of the abstract and conclusions. -- [ ] Avoid informal language -- [ ] No superlatives (e.g., _very complicated_) -- [ ] Limit the use of conjunctive (connecting) words (e.g., however, moreover). It's ok just to start a sentence! -- [ ] Limit repetitive words (don't substitute using the thesaurus, re-evaluate the sentences) -- [ ] Don't use spoken contractions (e.g., it's) - -### Required watching - -Before writing a paper, watch these two lectures from the University of Chicago: -* [The Craft of Writing Effectively](https://www.youtube.com/watch?v=vtIzMaLkCaM) -* [Writing Beyond the Academy](https://www.youtube.com/watch?v=aFwVf5a3pZM) - -### Other links - -Over the years, I found the documents below helpful for improving my writing: - -* [Toward a good scientific writing](https://link.springer.com/article/10.1007/s40071-014-0080-8) -* [Terry Tao's advice](https://terrytao.wordpress.com/advice-on-writing-papers/) -* [Improving your scientific writing: a short guide](https://lijunsun.github.io/files/ScientificWritingV39.pdf) -* [Knuth Mathematical Writing Guide](https://tex.loria.fr/typographie/mathwriting.pdf) -* [Three Sins of Authors in Computer Science and Math](http://www.cs.cmu.edu/~jrs/sins.html) -* [How to write a great research paper](https://www.microsoft.com/en-us/research/academic-program/write-great-research-paper/) -* [Notes on writing](http://people.csail.mit.edu/fredo/PUBLI/writing.pdf) -* [How to Write a Good Article](http://people.csail.mit.edu/fredo/FredoBadWriting.pdf) -* [Ten simple Rules for Responsible referencing](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006036#sec001) -* [Writing a science paper some dos and don'ts](https://www.elsevier.com/connect/writing-a-science-paper-some-dos-and-donts) -* [Experimental Biosciences writing science](http://www.ruf.rice.edu/~bioslabs/tools/report/reportform.html) -* [11 steps to structuring a science paper editors will take seriously](https://www.elsevier.com/connect/11-steps-to-structuring-a-science-paper-editors-will-take-seriously) -* [Strunk and Write](https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X) is a classical book that describes common writing gaffs and style particulars. -* [Move over Strunk and White: My all-time favorite books on writing](https://clauswilke.com/blog/2017/11/12/move-over-strunk-and-white/) - - +# Academic writing + +**Companion documents: [Formatting your work](formatting.md), [Improving your writing](improving-your-writing.md), [Making a figure](figures.md), [Responding to reviewers](responding-to-reviewers.md)** + +## Why should I read this? + +Many students have trouble producing scientifically acceptable writing without significant training. +(I use "scientifically acceptable" as a suitcase word for whatever seasoned academics find appropriate in journal papers.) +Perhaps this isn't surprising; students do not formally learn how to do this. + +This difficulty is juxtaposed with just how important your writing is. +You likely will only remember some details of your past research projects. +Instead, you'll be able to use your papers as references. +Other scientists won't see your research notes (nor would you want them to) or know the details of your academic past. +Instead, they will judge you based on your archived writing (conference proceedings and journal articles). +Only a few opportunities exist to side-step this. +Giving conference and invited talks communicates your research without paper-in-hand. +However, this format is ephemeral. +Anyone interested in your talks can find your papers to understand your contributions without time constraints. +It is also two-way coupled: you will likely only be invited to give talks with the presumption of good papers behind them. + +Careful writing also begets careful thinking (and vice-versa). +That is, forcing yourself to clarify and organize your work will bring problems in your thinking to light. +Because of this, improving your writing as soon as possible can be useful. +New students may well be over a year from starting a manuscript for a journal. +However, they, too, will benefit from carefully writing up their notes, ideas, and plans. + +For the above reasons, high-quality scientific writing is often expected from students ready to graduate with their Ph.D. +I invite you to use this document to bootstrap your way to scientifically-acceptable technical writing. + +From a now-deleted StackExchange post on "pet peeves in academic writing": +> Ernest Hemingway wrote, "the only kind of writing is rewriting." E. B. White wrote essentially the same thing: "The best writing is rewriting." +> +> I have plenty of pet peeves about academic writing, but they all seem to have the same cause: that the author apparently didn't care about writing well. +> +> Your first version of anything is likely to be mediocre. (That's certainly true for me!) Care about your own writing, enough to notice and be annoyed by shortcomings in your first draft, and then figure out how to improve it. Do this, and you will be well on your way to excellent writing. + +Also see: [Does writing matter a lot in research?](https://academia.stackexchange.com/questions/107919/does-writing-matter-a-lot-in-research) + +## Automatic grammar, spelling, and syntax checkers + +Several of these exist. +I use [Grammarly](https://www.grammarly.com/). +It offers a free tier and a trial of the "pro" service at the time of writing. +I purchased the full Grammarly and do not regret the purchase. +The [Angry Reviewer](https://www.angryreviewer.com/) tool is also helpful for giving line-by-line feedback. +A general list of rules used in this tool is available [here](https://www.angryreviewer.com/rules). +We elaborate on this below. + +These tools can check for simple things, like improper spelling and grammar. +They can also identify more complicated style-related things, such as active and passive voices, repeated words and sentence-starters, "sticky sentences" (run-on sentences held together by many articles), and so on. + +I recommend using one of these before submitting any paper or abstract. +Often, even seemingly obvious mistakes can go unnoticed after so many revisions. +Such mistakes are a quick way for an editor or reviewer to perceive your work as careless (e.g., does he conduct his simulations like he writes his abstracts?!), even if only subconsciously. + +## Consistency + +One should keep styles consistent within a manuscript. +You might be forgiven for even poor style choices if you are consistent. +Please look at the [these](formatting.md) documents for more. +Note that this consistency extends to the level of detail throughout the paper. +A detailed introduction is best matched with a results section that achieves a similar level of detail. + +## Nomenclature + +Changing technical terms mid-way through a paper in the name of style will confuse people. +If your domain is a cylinder, don't switch to "tube" at any point. +If you call your model a "physical model," do not switch to calling it a "numerical model" (with the additional problem that these two things aren't the same, anyway). +If you define your "mesh spacing" in one section, don't switch to "grid spacing" or "mesh resolution" later on. +Don't use software-specific nomenclature. +This confuses readers if they haven't used the software, and they may not plan to use it. + +## Variable Naming + +Names of variables should make sense for an outside reader. +The objective is to make the paper as easily readable as possible. +In some cases, there may be a standard variable used for the value. +For example, consider how $c$ is used to denote the speed of sound. +Using $m$ to denote the speed of sound is not invalid, but may be confusing at the outset. + +Beware of using too many distinct variables for quantities, especially related ones. +This leads to confusion for the reader, who now must keep track of a variable table on top of the content of the work. +Make use of subscripts to annotate the variable and simplify the naming scheme. +For example, suppose we have the following values to be used in equations: + +- Number of samples +- Number of lattice sites +- Number of dimensions + +We may use $M$, $N$, and $K$ to denote each of these quantities. +However, this is confusing and fails to show that we are simply counting the "number of [something]". +Instead, denote the values using variables $N_{samp.}$, $N_{sites}$, and $N_{dim.}$. + +## Concise writing + +One should prefer using as few words as required when describing something technical. +You can consult replacement lists for common mistakes: + +* [Wordy phrases](https://grammarist.com/wordiness/) +* [Wordy phrase replacements](https://www.kingcounty.gov/help/editorial-style-guide/concisewriting/wordyphrases.aspx) +* [Wordiness, Wordiness, Wordiness List](https://web.uvic.ca/~gkblank/wordiness.html) +* [50 Plain-Language Substitutions for Wordy Phrases](https://www.dailywritingtips.com/50-plain-language-substitutions-for-wordy-phrases/) + +These lists help me realize, "Hey, I write wordy phrases like this all the time!" +Use the lists to learn the general ways one ends up with low information-density writing. +You can then identify similar phrases in your writing. +Often, eliminating them is relatively easy, but noticing them is (at first). + +Conciseness can be viewed in a broader sense. +For example, you should structure your paragraphs such that you aren't repeating information. +Other tips of this type are available at these links: + +* [Writing Concisely – The Writing Center • University of North Carolina at Chapel Hill](https://writingcenter.unc.edu/tips-and-tools/conciseness-handout/) +* [Writing Clearly & Concisely](https://writingcenter.ashford.edu/writing-clearly-concisely) +* [Tips for being concise in academic writing](https://lauraripperproofreading.com/2018/01/26/how-to-be-concise-tips-for-academic-writing/) + +## What goes where + +__Always__ have a narrative first figure demonstrating what you are doing and "telling the overall story." +Take time to make this figure as attractive as possible. +It is one of the first things your readers will see! +See, for example, the first figure in my paper, "Fast Macroscopic Forcing Method." + +* Abstract + * Include a full, self-contained mini-version of your paper, including an introduction to your method, quantitative measures of your results, and conclusion and takeaways. +* Introduction (in this order) + * What is your work? + * Why are you doing it? + * What is the open problem you are trying to solve? + * What are some methods related to your work? + * What key contributions will you add? (without full detail) + * What does the rest of the manuscript contain? +* Acknowledgments + * We always have an unnumbered acknowledgment section before the references but after the discussion/conclusions. This is where we acknowledge funders and those who have helped with the work but are not authors. +* Future work + * I recommend not including a future work section in your papers or presentations + +## Guidelines, tips, and more! + +### Things to avoid; from the [Angry Reviewer](https://www.angryreviewer.com/rules) + +* Don't hype. Avoid words like novel, highly, clearly, greatly. Better still, avoid all adverbs. +* Don't use clichés. In a nutshell, by and large, they are clear as mud. +* Don't use "very" very often. Usually, there is a better word for it. +* Be concise. Avoid phrases like "by means of, despite the fact that, in order to". +* Avoid negatives. For example, use "unable" instead of "not able". +* Avoid redundancy. For example, use "investigate" instead of "conduct an investigation of". +* Use active voice. Although not always possible, most text should be in an active voice. +* Avoid inappropriate language. Keep words like "really, actually, pretty much" for social networks. +* Avoid rare words and latinisms. Non credo all readers know the meaning. +* Keep abbreviations to a minimum. Abbreviations are hard to read, consider just spelling it out. +* Beware of zombie nouns. Utilization of nominalization is the causation of distraction. + +### From [some tips for scientific writing](https://kucharski.substack.com/p/some-tips-for-scientific-writing) + +* Use the "show, don't tell" technique. If something is interesting or surprising, the reader should be interested or surprised by what they've read. They shouldn't need to be told. Anton Chekhov reportedly said: "Don't tell me the moon is shining; show me the glint of light on broken glass." + +* Don't bury the lede. When journalists write articles, they usually include crucial information in the opening paragraph. Hiding big news later in the piece is known as "burying the lede." This idiom forms part of the inverted pyramid approach to writing: put the most important information first in an article or section, then fill out the details. + +* Read widely, reflecting as you go. Why was that sentence hard to follow? Why did you like that section of text? Why was that turn of phrase annoying? What gave that paragraph its nice balance and rhythm? As Toni Morrison once put it: "Writing is a way of thinking – not just feeling but thinking about things that are disparate, unresolved, mysterious, problematic or just sweet." + +* Make your readers care about what they're reading. Like a good story, this typically means outlining a clear problem and promising a later resolution. + +* Some anonymous entities didn't do the analysis. You did the analysis. So avoid the passive voice if possible. (See also: "a decision was made" rather than "we made the decision" when it comes to responsibility-dodging in leadership messages.) + +* If you promise something in the introduction, ensure you've delivered by the end of the results. For example, if you open by mentioning A and B, readers will be expecting a conclusion about A and B by the end of the paper. "Remove everything that has no relevance to the story,' as Chekhov put it. "If you say in the first chapter that there is a rifle hanging on the wall, in the second or third chapter, it absolutely must go off." + +* Follow Orwell's rules of writing + * Never use a metaphor, simile, or other figure of speech that you are used to seeing in print. + * Never use a long word where a short one will do. + If it is possible to cut a word out, always cut it out. + * Never use the passive where you can use the active. + * Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. + * Break any of these rules sooner than say anything outright barbarous. + +* Kill your darlings. Sometimes, you'll write a so elegant and well-crafted phrase that it jars with the rest of your writing and pulls the reader out of the flow. So cut it. As Stephen King once put it: _'Kill your darlings, kill your darlings, even when it breaks your egocentric little scribbler's heart, kill your darlings.'_ + +* If you want to describe a figure/table in the results text, it can help to imagine you're giving a seminar. What features would you draw your audience's attention to? What would you tell people about during coffee break? + +* Help the reader interpret your figures and tables. Don't give them a sixteen-panel graph and expect them to spot the main takeaway; if the author can't be bothered to find a key message, the reader almost certainly won't either. + +* You can probably cut your word count by about half if you need to, without losing meaning. (I've managed to cut down a bunch of paper submissions into much shorter report formats when pressed.) + +* A good intro and discussion will often include a reference or statistic most readers won't have been aware of. Try and find the best references, rather than the easiest ones. + +### From [Koen Hufkens](https://github.com/khufkens/paper_writing_checklist) + +His document covers a small subset of components of a well-written manuscript. +Some of these are soft writing rules/guidelines. +They can be broken, but before breaking them, one usually has to understand why they exist. +If you consciously break a rule in your view for a good reason, then go for it. +Otherwise, stick to the guidelines. + +- [ ] Use active language +- [ ] Avoid long sentences +- [ ] Simplify your language (_no thesaurus_) +- [ ] One paragraph communicates one important idea +- [ ] Connect paragraphs and ideas in a logical order +- [ ] Use the present tense for the main part of the manuscript; past tense is allowed in some parts of the abstract and conclusions. +- [ ] Avoid informal language +- [ ] No superlatives (e.g., _very complicated_) +- [ ] Limit the use of conjunctive (connecting) words (e.g., however, moreover). It's ok just to start a sentence! +- [ ] Limit repetitive words (don't substitute using the thesaurus, re-evaluate the sentences) +- [ ] Don't use spoken contractions (e.g., it's) + +## Required watching + +Before writing a paper, watch these two lectures from the University of Chicago: + +* [The Craft of Writing Effectively](https://www.youtube.com/watch?v=vtIzMaLkCaM) +* [Writing Beyond the Academy](https://www.youtube.com/watch?v=aFwVf5a3pZM) + +## Other links + +Over the years, I found the documents below helpful for improving my writing: + +* [Toward a good scientific writing](https://link.springer.com/article/10.1007/s40071-014-0080-8) +* [Terry Tao's advice](https://terrytao.wordpress.com/advice-on-writing-papers/) +* [Improving your scientific writing: a short guide](https://lijunsun.github.io/files/ScientificWritingV39.pdf) +* [Knuth Mathematical Writing Guide](https://tex.loria.fr/typographie/mathwriting.pdf) +* [Three Sins of Authors in Computer Science and Math](http://www.cs.cmu.edu/~jrs/sins.html) +* [How to write a great research paper](https://www.microsoft.com/en-us/research/academic-program/write-great-research-paper/) +* [Notes on writing](http://people.csail.mit.edu/fredo/PUBLI/writing.pdf) +* [Adam Wierman: Advising](https://web.archive.org/web/20230401/http://users.cms.caltech.edu/~adamw/advising.html) +* [How to Write a Good Article](http://people.csail.mit.edu/fredo/FredoBadWriting.pdf) +* [Ten simple Rules for Responsible referencing](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006036#sec001) +* [Writing a science paper some dos and don'ts](https://www.elsevier.com/connect/writing-a-science-paper-some-dos-and-donts) +* [Experimental Biosciences writing science](http://www.ruf.rice.edu/~bioslabs/tools/report/reportform.html) +* [11 steps to structuring a science paper editors will take seriously](https://www.elsevier.com/connect/11-steps-to-structuring-a-science-paper-editors-will-take-seriously) +* [Strunk and Write](https://www.amazon.com/Elements-Style-Fourth-William-Strunk/dp/020530902X) is a classical book that describes common writing gaffs and style particulars. +* [Move over Strunk and White: My all-time favorite books on writing](https://clauswilke.com/blog/2017/11/12/move-over-strunk-and-white/) diff --git a/group-syllabus/intro-to-group.md b/docs/group-syllabus/intro-to-group.md similarity index 85% rename from group-syllabus/intro-to-group.md rename to docs/group-syllabus/intro-to-group.md index 5ac4207..4e4365c 100644 --- a/group-syllabus/intro-to-group.md +++ b/docs/group-syllabus/intro-to-group.md @@ -1,18 +1,3 @@ - - -## Table of Contents - -- [Welcome to the Computational Physics @ GT CSE research group!](#welcome-to-the-computational-physics--gt-cse-research-group) - - [Getting started](#getting-started) - - [CODA](#coda) - - [Websites, software, course numbers, and such](#websites-software-course-numbers-and-such) - - [Computers](#computers) - - [Research meetings](#research-meetings) - - [Group GitHub Page](#group-github-page) - - [Collaboration](#collaboration) - - [Social activities](#social-activities) - - # Welcome to the Computational Physics @ GT CSE research group! @@ -20,14 +5,14 @@ The most important thing about this document is that I/we are _very glad_ to hav You wouldn't be a part of the group otherwise. This document has some parts that are specific to Ph.D. students, but much of it applies to undergraduate researchers in the group as well. -## Getting started +## Getting started ### CODA You will need access to the CODA building. GT CSE is on floor 13, and our group is in room S1347. We also hold meetings either in my office (S1313) or one of the conference rooms on the 13th floor. -Request this from Spencer. +Request this from Spencer. Send him your GTID number. Though times vary, it will likely take a week to "start working." ### Websites, software, course numbers, and such @@ -41,16 +26,16 @@ Send him your GTID number. Though times vary, it will likely take a week to "sta * If you're reading this, you already have access. * Zotero, located [here](https://www.zotero.org/groups/4507615/comp-physics/library) - * We have an unlimited shared Zotero group where you should post papers and books relevant to your studies. I also randomly reference many texts, and you can often find them available here. + * We have an unlimited shared Zotero group where you should post papers and books relevant to your studies. I also randomly reference many texts, and you can often find them available here. * It has an iPhone app, a MacOS/*nix app, a web interface, etc. It is very convenient. After using both significantly, I prefer it over Mendeley. * Request access from Spencer. - + * Group email list * Upon joining, remind Spencer to add you to the `comp-physics@office365.gatech.edu` email list - + * Group website, located [here](https://comp-physics.group/team/) * Send Spencer a headshot and your LinkedIn, ResearchGate, personal/research website, Google Scholar, etc. for the website - + * Taking a "special problems" or research "class" with me? Find the course and section number for me below * For graduate students * CSE @@ -79,11 +64,12 @@ We maintain a separate page on this [here](computers.md) ## Research meetings -You will usually have a meeting with Spencer every week (often on Monday). +You will usually have a meeting with Spencer every week (often on Monday). These sometimes involve you and another student (2-1 meetings). During this meeting, you will present an update on your research. We also have an in-person group meeting every week. Some guidelines apply: + * Have at least one PowerPoint slide for each update, stating the work you did and plan to do in the next week (see examples in the Box `updates/` directory). * If you make little progress, that's OK! In fact, the weeks you make the least progress are the most important for updates since my job (in part) is to help you. * Even if you have little progress because you were busy with coursework or on a vacation, please put this on a slide so I can keep track of things. @@ -98,12 +84,12 @@ It also allows us to collaborate freely with corporations, like those at NVIDIA ## Collaboration -You are expected to collaborate with your colleagues when appropriate. +You are expected to collaborate with your colleagues when appropriate. Your colleagues are students within the group and the school more broadly. Part of this is willingly and openly sharing your [code](https://opensource.google/docs/why/) and [ideas](https://www.ted.com/talks/steven_johnson_where_good_ideas_come_from?language=en). It makes us all better researchers. ## Social activities -We try to arrange a group social activity at least every few months. +We try to arrange a group social activity at least every few months. This means things like going to a neighborhood restaurant or a trivia night, but we do an anonymous poll to see what everyone would enjoy. diff --git a/group-syllabus/publishing.md b/docs/group-syllabus/publishing.md similarity index 91% rename from group-syllabus/publishing.md rename to docs/group-syllabus/publishing.md index 9391b2b..5508bd4 100644 --- a/group-syllabus/publishing.md +++ b/docs/group-syllabus/publishing.md @@ -1,16 +1,5 @@ - - -## Table of Contents -- [Publishing](#publishing) - - [Important: The "-X days" internal revision process and deadlines](#important-the--x-days-internal-revision-process-and-deadlines) - - [Process: writing alone, better together](#process-writing-alone-better-together) - - [Co-authorship](#co-authorship) - - [Conference and Other Presentations](#conference-and-other-presentations) - - - -## Publishing +# Publishing **Companion documents: [Formatting your work](formatting.md), [Improving your writing](improving-your-writing.md), [Making a figure](figures.md), [Responding to reviewers](responding-to-reviewers.md)** @@ -22,7 +11,7 @@ I recommend finding exemplary papers from the target venue to use as referrals a While you can and will work with me directly on papers (as I expand on below), my time will always be limited. There is no substitute for interactively thinking about your writing compared to other similar scholarship. -### Important: The "-X days" internal revision process and deadlines +## Important: The "-X days" internal revision process and deadlines I have an internal deadline of "-X days" for abstracts, presentations, and papers. Anything with a deadline must be in the best state you can create __X__ days beforehand, where __X__ is the 7 + the number of pages the document is. @@ -68,7 +57,7 @@ You can always improve it by changing minor details and iterating back and forth If you hold back your work from me, especially if it means missing a deadline, I will have much less time to help you. If you miss a deadline sufficiently, I will not have time to review your work and thus won't be able to use it. -### Process: writing alone, better together +## Process: writing alone, better together Part of your development as a scholar is being able to plan, outline, and write an academic paper. I will be your co-author and collaborator for most of your papers. @@ -87,7 +76,7 @@ I use the raw `git` interface so I can use `vim` for my typing and compiling loc This is particularly useful for generating the `.pdf` files for independent `tikz`/`pgfplots` figures. You get a free Overleaf Pro account with your `gatech.edu` email address. -### Co-authorship +## Co-authorship As is common in our field, I will likely be a co-author on the papers we work on, which generally means most, if not all, of the papers you lead. Further, papers (and projects) often involve other collaborators, including faculty, PhD students, and MS/undergraduate students. @@ -99,7 +88,7 @@ If you feel uncomfortable with authorship or ordering, please raise it with me i Once a paper or abstract is accepted, authorship cannot changed. All authorship concerns should be resolved before submission, preferably even as collaborations are budding. -### Conference and Other Presentations +## Conference and Other Presentations With many of our papers submitted to highly peer-reviewed conferences, you can expect to be able to present your research in conferences (and similar settings), often to dozens, if not hundreds, of people. Later in your Ph.D., you will likely have other research presentations, including seminars and job talks. @@ -108,4 +97,3 @@ You should expect more of this feedback and iteration earlier in your Ph.D.; it I will also likely present your research in invited talks, lectures, and seminars. I will give you credit when I do so. - diff --git a/group-syllabus/responding-to-reviewers.md b/docs/group-syllabus/responding-to-reviewers.md similarity index 82% rename from group-syllabus/responding-to-reviewers.md rename to docs/group-syllabus/responding-to-reviewers.md index 66cdd1a..512b854 100644 --- a/group-syllabus/responding-to-reviewers.md +++ b/docs/group-syllabus/responding-to-reviewers.md @@ -1,16 +1,5 @@ - - -## Table of Contents -- [Responding to reviewers](#responding-to-reviewers) - - [Principle of charity](#principle-of-charity) - - [Knowing what to and not to do](#knowing-what-to-and-not-to-do) - - [The details of a response document](#the-details-of-a-response-document) - - [Examples](#examples) - - - -## Responding to reviewers +# Responding to reviewers When you submit a paper, you will likely get reviews that request changes to your work. These changes may be major or minor. @@ -19,7 +8,7 @@ Sometimes, the reviewer may not fully appreciate your manuscript, so the questio You should be prepared for all such situations. Ultimately, it is up to you to make your contributions crystal clear and tell a complete story accessible to __your audience__. -### Principle of charity +## Principle of charity While you may want to defend your work, thinking something like, "This reviewer didn't even read the paper!", I recommend a more balanced approach. If they didn't read your paper deeply and comprehensively, why not? @@ -35,7 +24,7 @@ In these cases, you should respond carefully and point the reviewer to the part You likely will want to reword certain parts of the paper so that you can say something like > We agree that X was unclear, though it was discussed in Section Y.Z. We have rephrased and clarified paragraph A of this section to clarify point B. Below is the revised text: -### Knowing what to and not to do +## Knowing what to and not to do Sometimes, a reviewer will request you to do significant extra work for a paper. Whether or not you should do this rests on many choices. @@ -45,21 +34,23 @@ Ultimately, this is a rather sensitive topic, and one has to be careful with wor I will help you decide what should and shouldn't do. Regardless, you should be grateful for the reviewer's contributions towards a better manuscript. -### The details of a response document +## The details of a response document + +When you create a response document, make sure to -When you create a response document, make sure to * Be specific with references to sections and figures! Use the specific section you are talking about and include many quotes of the new text that you added to address their concerns (these should be in a different color than the main reply) -* Defer to the reviewer unless there is a good reason not to. Many issues can be solved by simply agreeing with the reviewer, thanking them for the comment, and correcting the manuscript accordingly. +* Defer to the reviewer unless there is a good reason not to. Many issues can be solved by simply agreeing with the reviewer, thanking them for the comment, and correcting the manuscript accordingly. * If the reviewer is clearly wrong or misunderstanding the paper, this is (usually) on you. Perhaps you should have been more clear in your exposition! You should apologize for any confusion, clarify what you meant, and bolster that part of the paper with references, discussion, and clarity. You should include all of this in your reply to them and apologize for any confusion you caused. -* This is a formal document. Treat it as such. Do not be lax with your grammar or writing. +* This is a formal document. Treat it as such. Do not be lax with your grammar or writing. -### Examples +## Examples There are examples in this repository, including -* A Revision template [in this directory](../templates/paper_rebuttal) + +* A Revision template [in this directory](https://github.com/comp-physics/group-docs/tree/master/templates/paper_rebuttal) * In the same place, a `Makefile` that uses the `latexdiff` tool to create a `diff` between the submitted (`main.tex`) and revised (`main_rev.tex`) manuscript files in the form of a new PDF file called `diff.pdf`. This shows the reviewer explicitly all the changes you made to improve the paper (on top of the revisions in the response to the reviewers document). diff --git a/group-syllabus/undergraduate-specifics.md b/docs/group-syllabus/undergraduate-specifics.md similarity index 85% rename from group-syllabus/undergraduate-specifics.md rename to docs/group-syllabus/undergraduate-specifics.md index 194b056..2b5c270 100644 --- a/group-syllabus/undergraduate-specifics.md +++ b/docs/group-syllabus/undergraduate-specifics.md @@ -1,42 +1,26 @@ -## Somewhat specific to undergraduates +# Somewhat specific to undergraduates Much of this 'syllabus' applies to undergraduates and graduate students. But, there are a few things specific to undergraduate researchers. Below is my attempt to explain them. - - -## Table of Contents - -- [Meetings](#meetings) -- [Remote work](#remote-work) -- [Money](#money) -- [Time and commitment](#time-and-commitment) -- [Outcomes](#outcomes) -- [Ph.D.?](#phd) -- [Internships](#internships) -- [Office space](#office-space) -- [Working with people](#working-with-people) -- [Going to conferences](#going-to-conferences) - - - -### Meetings +## Meetings Following much other text in this set of documents, I expect in-person attendance from all students I advise. Not getting much "work done" is not an acceptable reason to cancel meetings, in my view. There is always a lot to talk about regarding your work. If there isn't, you don't need me to advise you! -### Remote work +## Remote work * I _do not_ fund students to work remotely in my group (e.g., over the Summer). * I _do not_ hold regular scheduled meetings with unfunded remote students. -### Money +## Money You can be paid a modest sum as an undergraduate researcher. This comes in the form of funding routed through either + * A federal grant (via Spencer) * A salary award from Georgia Tech, called [PURA Salary](https://urop.gatech.edu/pura-salary). @@ -47,14 +31,14 @@ For example: > SPRING 2024 APPLICATION DEADLINE > FRIDAY, September 29, 2023 -Details on the review rubric for PURA Salary are found [here](../misc/pura-salary-review-rubric.pdf) +Details on the review rubric for PURA Salary are available from the [PURA website](https://urop.gatech.edu/pura-salary). I do not fund undergraduate researchers during their first semester or year working with the group. This is primarily due to the start-up time required to get familiar with any project and contribute more directly. The same reasoning applies to why I don't accept undergraduate researchers graduating within two years. Conducting scientifically impactful research takes time (see below). -### Time and commitment +## Time and commitment __Note:__ Please read [The When and Where of Working](when-where-working.md) @@ -67,17 +51,18 @@ Taking fewer classes might mean graduating in 4 years instead of 3 (or something You must consider this trade-off on your terms, though I'm glad to discuss it with you. GT CS offers an undergraduate thesis option, which meets several degree requirements but is otherwise a small time commitment (and teaches you useful things!). -Some commitment topics to consider: -* If you hope to go to a top graduate school (or are considering it), at Georgia Tech or otherwise, completing your degree early is unlikely to help with admission, but completing high-quality research _definitely_ will. +Some commitment topics to consider: + +* If you hope to go to a top graduate school (or are considering it), at Georgia Tech or otherwise, completing your degree early is unlikely to help with admission, but completing high-quality research _definitely_ will. * If you don't think you do not want to go to graduate school, research can still expand industry opportunities. The degree to which it expands those opportunities will depend on the job you hope to obtain. Discuss with Spencer for more details. -### Outcomes +## Outcomes The goal of performing research, in part following the above, is to produce scientifically impactful work. As such, one should aim to produce work that one "owns" that was not primarily conducted by someone else. One can argue that this alone is an intrinsic good. -Still, that work should be worthy of a top conference or journal venue (the latter is more typical of our work). +Still, that work should be worthy of a top conference or journal venue (the latter is more typical of our work). Such papers are tangible outputs and, in part, serve as a stamp from a research community saying, "You conducted and communicated scientifically meaningful and important research." Without such a "stamp," it is harder to convince others (future employers, for example) that your work is important to the community. Strong letters of recommendation are great. First-author journal papers are often much better (if you are an undergraduate). @@ -85,37 +70,38 @@ The above two things are often strongly correlated. __It takes about two years to research and write a journal paper, plus additional months for review and publication.__ -### Ph.D.? +## Ph.D.? If you are interested in continuing to a Ph.D. at GT or elsewhere, there are a few extra things worth noting. + * Having a journal or conference paper(s) in top venues will strongly improve your chances of admission. * Having _extremely_ strong references, even just one(!) (in this case, likely me), can get you into a top Ph.D. program. I will write a letter faithful to your work with me and the group. Should you get a Ph.D.? This can be a tough question and is quite individualized. You should talk about it with me if you are thinking about it. -### Internships +## Internships If you want to participate in an internship, I will gladly support you in your search. I can guide you more closely if you want your internship to work well with your research. Whether you should or should not take on an internship will depend on several factors, depending on your goals upon graduation and your research area. I recommend you talk about this with me so I can give more personalized guidance. -### Office space +## Office space You will have a desk to use, including a 32" 4K monitor, keyboard, and mouse, in the group office space on the 13th floor of CODA. You are always welcome to use the CODA spaces on the 13th floor or otherwise. These areas seem quite pleasant to me, but you may disagree. If you would like somewhere to work but are still looking for a comfortable place, please let me know. -### Working with people +## Working with people __Prioritize__ being in proximity to other group members. Your colleagues are there to help you. Using them effectively, whether you are a UG or not, and whether they are a UG or not, betters both of you and will undoubtedly accelerate your research. If you are not making consistent contact with your colleagues, I will notice and suggest you do so. -### Going to conferences +## Going to conferences If you have made significant research progress, you can present it at a conference! I have sent several undergraduates to conferences; nearly all UGs that worked with the group for > 1 year. @@ -124,5 +110,4 @@ You should apply for [PURA Travel](https://urop.gatech.edu/pura-travel). It is a rather short proposal that is easy to put together. Some example successful proposals are [here](https://gatech.app.box.com/folder/227839379429). -Undergraduates __do not__ need to complete a Georgia Tech Spend Authorization (but graduate students do). - +Undergraduates __do not__ need to complete a Georgia Tech Spend Authorization (but graduate students do). diff --git a/group-syllabus/when-where-working.md b/docs/group-syllabus/when-where-working.md similarity index 89% rename from group-syllabus/when-where-working.md rename to docs/group-syllabus/when-where-working.md index d43aa09..7f8d641 100644 --- a/group-syllabus/when-where-working.md +++ b/docs/group-syllabus/when-where-working.md @@ -1,15 +1,5 @@ - - -## Table of Contents -- [The Where and When of Working](#the-where-and-when-of-working) - - [Are you working enough? Or too much?](#are-you-working-enough-or-too-much) - - [Can I take a vacation?](#can-i-take-a-vacation) - - [Work location](#work-location) - - - -## The Where and When of Working +# The Where and When of Working One of the biggest challenges for student researchers is time management. I will help you set long-term and short-term goals but never directly manage your time or tasks. @@ -22,14 +12,14 @@ At a high level, you should have a set of daily tasks, but also some higher leve I will help you set those, typically going to larger and larger time frames as your research advances. For time and task management, use whatever tool works for you: notebooks, task manager apps, text files, etc., but make sure to use _something_. -### Are you working enough? Or too much? +## Are you working enough? Or too much? Some parts of this section are particularly applicable to undergraduate student researchers. _How much time are you expected to work?_ There is no one answer to this, but I can put some upper and lower bounds that apply to nearly everyone: * (Particularly pertinent for UG researchers) You are not working enough if you __do much of your work a few hours before meetings__ - * If this is you, you should take fewer courses or dedicate more time to research. + * If this is you, you should take fewer courses or dedicate more time to research. * _At the very least_, as an undergraduate, you should be working on research at least __10 solid, uninterrupted hours per week__ (on average). However, the more you put in, the more you get out, with some exceptions (see below). * No matter how clever and smart you are (which you probably are), if you do not spend enough time on your work, you are (in my experience) highly unlikely to produce a polished piece of fundamental research. These things take _time_ (unfortunately). @@ -47,8 +37,8 @@ There is no one answer to this, but I can put some upper and lower bounds that a * Our schedules vary wildly. Getting little done in one week is not much of a signal. Getting little done many weeks in a row, or on average, is more concerning. * You got less "visible stuff" done than your colleague * Every project is different. Some projects take significant time and effort before one can see fancy videos or nice results (and others are the opposite). - -### Can I take a vacation? + +## Can I take a vacation? You can and should take time off whenever you need it. Unhappy or overworked people are unproductive (at least eventually). @@ -56,10 +46,11 @@ So, from a purely pragmatic point of view, it is also in my best interest that y __Do what you need to do to stay happy and healthy.__ Two caveats: + * Avoid taking extra time off near important deadlines when possible (we can discuss and resolve if there is a potential conflict). * Communicate with me. If you are not going to be around, let me know because I may need to arrange around this. Also, in case I forget, put a slide in your "updates" slides that says you are out of town. -### Work location +## Work location We work in CODA, which has an open space layout, and the group's students sit near each other. You will have an assigned desk in or near room S1347. diff --git a/group-syllabus/why-phd.md b/docs/group-syllabus/why-phd.md similarity index 87% rename from group-syllabus/why-phd.md rename to docs/group-syllabus/why-phd.md index b051b68..cf986b6 100644 --- a/group-syllabus/why-phd.md +++ b/docs/group-syllabus/why-phd.md @@ -1,13 +1,5 @@ - - -## Table of Contents -- [The What and Why of a Ph.D.](#the-what-and-why-of-a-phd) - - [How long is a Ph.D.?](#how-long-is-a-phd) - - - -## The What and Why of a Ph.D. +# The What and Why of a Ph.D. Advising and working with Ph.D. students is the *best part of my job*. In fact, it is probably the main reason I chose to be a professor. @@ -33,7 +25,7 @@ Toward these ends, I will aim to give you as much independence as I think you ca I try to assess this case-by-case; if you feel like I misjudged it any time (e.g., too much or too little), please let me know. The general path is increasing independence with increasing time. -### How long is a Ph.D.? +## How long is a Ph.D.? I believe that your Ph.D. is over when you: @@ -58,7 +50,5 @@ The usual "triangle" argument goes as * National laboratories: Medium pay, medium independence * Academia: Least pay, most independence. On a personal note, I heavily value the latter, and its often easier to hop from academia to industry than vice-versa. So, here I am. -The Ph.D. takes _very roughly_ 4-7 years, with students headed to the academic job market lean on the longer end, say 5-6. +The Ph.D. takes _very roughly_ 4-7 years, with students headed to the academic job market lean on the longer end, say 5-6. However, your work ethic, project(s), and more can shorten or lengthen this. - - diff --git a/group-syllabus/working-with-me.md b/docs/group-syllabus/working-with-me.md similarity index 90% rename from group-syllabus/working-with-me.md rename to docs/group-syllabus/working-with-me.md index d90f3d2..2b386f1 100644 --- a/group-syllabus/working-with-me.md +++ b/docs/group-syllabus/working-with-me.md @@ -1,19 +1,5 @@ - - -## Table of Contents -- [Working with Me](#working-with-me) - - [Advising "style"](#advising-style) - - [Spencer's quirks](#spencers-quirks) - - [Power Structures](#power-structures) - - [Co-advising](#co-advising) - - [Time with me and Others](#time-with-me-and-others) - - [How to get a hold of me](#how-to-get-a-hold-of-me) - - [Useful links](#useful-links) - - - -## Working with Me +# Working with Me The advisor-advisee relationship represents a significant responsibility and commitment on both our parts. I attempt to hold myself to high standards with students, but I also have high expectations from students who work with me. @@ -23,16 +9,16 @@ Note that the failure, or perceived failure, could also be due to my actions. I recognize that this is one of the most important and consequential relationships you will have; while I hope it will be at least as meaningful for me, it is less likely to be as consequential. As a result, I encourage you to let me know if something needs to be fixed. -### Advising "style" +## Advising "style" I am your _advisor_, not your manager, supervisor, or teacher. -I am not here to "boss you around" or to tell you what to do when, but I do provide suggestions, recommendations, and sometimes even decisions ("this paper is not good enough to submit for this deadline"), and I do expect to see various outcomes (and progress). +I am not here to "boss you around" or to tell you what to do when, but I do provide suggestions, recommendations, and sometimes even decisions ("this paper is not good enough to submit for this deadline"), and I do expect to see various outcomes (and progress). But I try to stay away from prescribing the details. Instead, I will help you set your plans and goals and the best way to reach them. -Of course, the power dynamics are somewhat tilted in my "favor," and I recognize that. +Of course, the power dynamics are somewhat tilted in my "favor," and I recognize that. I often fund your work, I sign your thesis, I report to the school on your progress, and more. Still, I welcome pushback from Ph.D. students (e.g., "I don't think we should run this simulation"), as well as healthy feedback and disagreement. -A relationship where we never disagree is unlikely to be a fruitful one. +A relationship where we never disagree is unlikely to be a fruitful one. If you are taking agency over your work, you will eventually feel that one of my suggestions could be better, and I encourage you to tell me. I also am unlikely to directly teach you the specific skills you need for your research tasks. @@ -40,21 +26,22 @@ I will not teach you Fortran or C++ (or any other programming language). I will not teach you how to launch an SSH session onto one of the university supercomputers. I _will_ help you get all these skills, though, by pointing you to the right resources when needed (e.g., courses, papers, tutorials, documentation, or knowledgeable others). -#### Spencer's quirks +### Spencer's quirks We all have our quirks and it is only fair to tell you mine as a fair warning. Some of these tendencies blend into what I consider professional behavior, but one could cast those as quirks. I take these rather seriously, so please read them. This list is surely incomplete, but it's what I've come up with for now. + * __Punctuality:__ I have little patience for tardiness (of myself or others). Arrive at meetings on time. If you cannot arrive at meetings on time, tell me why ASAP, and we can try rescheduling them! -* __(self-imposed) Deadlines:__ These are related to the above. If you say you will send me something on a certain date but then do not, I will be stressed and frustrated. Sometimes, the date you send me something is critical to our research group, and you will often be unaware if this is the case or not. Always communicate with me when you think you cannot meet a deadline, whether you self-imposed it or I did, and if needed in the future, give a more relaxed deadline for yourself: "I am not sure exactly how long this will take. I think I will have it for you by Tuesday, but it might take a few more days, so I am quite confident Friday is the worst-case situation." If you don't do this, and don't send me things when you say you will, we will both be stressed. Instead, let's communicate. +* __(self-imposed) Deadlines:__ These are related to the above. If you say you will send me something on a certain date but then do not, I will be stressed and frustrated. Sometimes, the date you send me something is critical to our research group, and you will often be unaware if this is the case or not. Always communicate with me when you think you cannot meet a deadline, whether you self-imposed it or I did, and if needed in the future, give a more relaxed deadline for yourself: "I am not sure exactly how long this will take. I think I will have it for you by Tuesday, but it might take a few more days, so I am quite confident Friday is the worst-case situation." If you don't do this, and don't send me things when you say you will, we will both be stressed. Instead, let's communicate. * __"No-call no-show":__ Do not miss meetings without letting me know. I make time for you (in the same way you sometimes make time for me!), so I consider it respectful behavior to let me know if you cannot make it (sick, out-of-town, or whatever). Also, add a slide in your "updates" slides that says you are unavailable/out of town so I don't forget and wonder where you are. * __Unresponsiveness:__ If I ask you something on Slack (or occasionally email), I expect a response within a few work days. The response can just confirm receipt ("acknowledged"). Of course, I do not expect this during holidays, weekends, vacation time, etc., and you may have other situational circumstances (e.g., you're sick or away at a family event) that prevent this. That is fine! Though please give me a heads-up. * __Demeanor:__ I have a rather deadpan effect most of the time. This has followed me around for my whole life and seems unlikely to change much, unfortunately, despite some efforts on my part. So, don't be shocked if I don't jump out of my chair with a giant smile when you show impressive and exciting results. I really am excited. It just isn't as externally obvious. Please do not let my demeanor damage your sense of self-worth. You are part of the group for a reason, and if I weren't excited to have you be part of it, then we wouldn't be working together anymore. * __Jokes:__ I sometimes make sarcastic jokes about myself or others that shouldn't be taken seriously. I realize these aren't always appropriate, and discerning that I'm joking is not always trivial. These are usually meant to keep the mood light and fun, though I'm trying to avoid at least most of them. * __Writing and style:__ I take academic writing and presentation quality seriously. Please read the rest of this syllabus to bootstrap your way to high-quality dissemination of your work. -### Power Structures +## Power Structures The university has strong hierarchical structures. Professors have power over students; unfortunately, students cannot always speak up when something isn't right. @@ -62,14 +49,14 @@ I welcome student input, especially if I or one of my colleagues has said or don I realize it is a difficult proposition in many cases, especially if you feel I am the culprit. If you feel you suffered an injustice, I encourage you to speak to me or other trusted individuals. -### Co-advising +## Co-advising I am a fan of co-advising Ph.D. students, and many of my students are, or have, been co-advised. As long as the "trio" dynamics are healthy, including the relationship between the two advisors, this is a good idea: it gives you another person to advise you and be invested in your future; it broadens the ideas and knowledge you are exposed to. There are potential drawbacks, some overhead for you (scheduling, more weekly and lab meetings), and potential friction when advisors disagree. But overall, if there are two faculty members whose work, vision, and interests align with yours, you should explore co-advising. -### Time with me and Others +## Time with me and Others I prioritize my time to maximize availability to talk research with students. Still, there are sometimes other requirements on my time, often immutable and sometimes urgent. @@ -82,7 +69,7 @@ Please feel free to ask for my time at any other point, e.g., for a quick ad-hoc Beyond the 1-1 meeting, you will be asked to attend the weekly group meeting where students share progress and other updates. You may also see me in project-specific meetings (the frequency of which depends on the project) when we collaborate with others. -### How to get a hold of me +## How to get a hold of me Our group Slack workspace is the best way to find me if I'm not in my office. My calendar is always available to the public [via this link](https://outlook.office365.com/calendar/published/89a8b6b3591343ecb432e9a56a04e5f3@gatech.edu/8133a21aea4c4970b3049d3fffee2c066536954178697437005/calendar.html). @@ -92,7 +79,7 @@ Checking via Slack is more reliable. __Note:__ If you want me to be responsive to you, you should be responsive to me. However, I do not expect you to be responsive during non-standard working hours (unless we agreed to be working on a deadline). -### Useful links +## Useful links * [The hacker attitude](http://www.catb.org/~esr/faqs/hacker-howto.html#attitude) * [How to ask questions the smart way](http://www.catb.org/~esr/faqs/smart-questions.html) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..7ab1dfe --- /dev/null +++ b/docs/index.md @@ -0,0 +1,37 @@ +# Computational Physics @ GT: Group Documentation + +Welcome! This is the documentation for the Computational Physics research group at Georgia Tech. + +**Getting started?** Head to [Welcome to the group!](group-syllabus/intro-to-group.md) + +**Syllabus** — +[Why a Ph.D.?](group-syllabus/why-phd.md) · +[Funding](group-syllabus/funding.md) · +[Working with me](group-syllabus/working-with-me.md) · +[Doing research](group-syllabus/doing-research.md) · +[Publishing](group-syllabus/publishing.md) · +[When and where of working](group-syllabus/when-where-working.md) · +[Going to conferences](group-syllabus/going-to-conferences.md) · +[Giving talks](group-syllabus/giving-talks.md) · +[Challenges](group-syllabus/challenges.md) · [FAQ](group-syllabus/faq.md) + +**Papers and Writing** — +[Academic writing](group-syllabus/improving-your-writing.md) · +[Formatting](group-syllabus/formatting.md) · +[Making figures](group-syllabus/figures.md) · +[Responding to reviewers](group-syllabus/responding-to-reviewers.md) + +**Details** — +[Undergraduate specifics](group-syllabus/undergraduate-specifics.md) · +[Available computers](group-syllabus/computers.md) · +[Hardware](group-syllabus/hardware.md) + +**Templates** — +[Papers](https://github.com/comp-physics/group-docs/tree/master/templates/paper) · +[Paper reviews](https://github.com/comp-physics/group-docs/tree/master/templates/paper_rebuttal) · +[Figures](https://github.com/comp-physics/group-docs/tree/master/templates/paper/figures) · +[Talks](https://github.com/comp-physics/group-docs/tree/master/templates/talks) + +--- + +© Spencer Bryngelson 2026 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..39b3613 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +zensical diff --git a/misc/mentoring-plan.md b/misc/mentoring-plan.md deleted file mode 100644 index 78d6f43..0000000 --- a/misc/mentoring-plan.md +++ /dev/null @@ -1,42 +0,0 @@ -# Mentoring Plan - -## Your name: [YOUR NAME HERE] -## Date: [DATE HERE] - -__The Past__ - -Over the last [period of time] - -* What did you _hope_ to accomplish? (it is OK if you didn't!) - -* What did you accomplish? - * Did you accomplish something you didn't anticipate finishing or doing? - * If so, how did you help make that happen? - * What might help it happen again in the future? - * Did you not accomplish something you did hope to finish? - * If so, what slowed you from accomplishing these? (a list is fine) - * How will you adjust to make your plans match your goals in the future? - -__The Future__ - -Over the next [period of time] -* What do you _hope_ to accomplish? -* What is your career goal upon graduating? (feel free to list more than one thing to the degree you are unsure!) -* [WIP] - - -__Misc__ -* Overall career goals -* Remaining skills and knowledge goals: what more you want to learn and practice at Georgia Tech -* Remaining publication “milestones:” what more you want to write during your time at Georgia Tech -* Fellowships, grants, and letters - * Targeted fellowships, grant applications -* Goals for next year - * Research projects - including sharpening questions, forming collaborations, etc - * Publications/submissions? - * Grants or fellowship applications? - * Meetings and conferences? - * Other professional development? - - -* What suggestions do you have for improving the mentoring you are getting? diff --git a/misc/pura-salary-review-rubric.pdf b/misc/pura-salary-review-rubric.pdf deleted file mode 100644 index 8f3da6b..0000000 Binary files a/misc/pura-salary-review-rubric.pdf and /dev/null differ diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..94bb692 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,65 @@ +site_name: "Computational Physics @ GT: Group Documentation" +site_url: https://comp-physics.group/group-docs/ +repo_url: https://github.com/comp-physics/group-docs +edit_uri: edit/master/docs/ +docs_dir: docs + +theme: + name: material + logo: assets/favicon.ico + favicon: assets/favicon.ico + font: + text: Source Sans Pro + palette: + - scheme: slate + primary: custom + accent: custom + toggle: + icon: material/brightness-4 + name: Switch to light mode + - scheme: default + primary: custom + accent: custom + toggle: + icon: material/brightness-7 + name: Switch to dark mode + features: + - navigation.sections + - navigation.top + - search.highlight + - content.action.edit + +extra_css: + - assets/extra.css + +extra_javascript: + - assets/mathjax.js + - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js + +markdown_extensions: + - pymdownx.arithmatex: + generic: true + +nav: + - Home: index.md + - Syllabus: + - Welcome: group-syllabus/intro-to-group.md + - Why a Ph.D.?: group-syllabus/why-phd.md + - Funding: group-syllabus/funding.md + - Working with me: group-syllabus/working-with-me.md + - Doing research: group-syllabus/doing-research.md + - Publishing: group-syllabus/publishing.md + - When and where of working: group-syllabus/when-where-working.md + - Going to conferences: group-syllabus/going-to-conferences.md + - Giving talks: group-syllabus/giving-talks.md + - Challenges: group-syllabus/challenges.md + - FAQ: group-syllabus/faq.md + - Papers and Writing: + - Academic writing: group-syllabus/improving-your-writing.md + - Formatting: group-syllabus/formatting.md + - Making figures: group-syllabus/figures.md + - Responding to reviewers: group-syllabus/responding-to-reviewers.md + - Details: + - Undergraduate specifics: group-syllabus/undergraduate-specifics.md + - Available computers: group-syllabus/computers.md + - Hardware: group-syllabus/hardware.md diff --git a/readme.md b/readme.md index 4ab6c09..a8c2a69 100644 --- a/readme.md +++ b/readme.md @@ -1,66 +1,9 @@ # Computational Physics @ GT Group Documentation -[![License: CC BY-NC 4.0](https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc/4.0/) -[![Georgia Tech](https://img.shields.io/badge/Georgia%20Tech-Computational%20Physics-b3a369)](https://comp-physics.group) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) +Documentation for the Computational Physics research group at Georgia Tech. -Welcome to the Computational Physics @ GT Group Documentation! This repository contains guidelines, expectations, and resources for group members. +**[Read the docs here](https://comp-physics.group/group-docs/)** -## 📚 Quick Navigation +## License -- [Welcome to the group!](group-syllabus/intro-to-group.md) -- [FAQ - Frequently Asked Questions](group-syllabus/faq.md) - -## 🎓 Syllabus - -| Topic | Description | -|-------|-------------| -| [Why a Ph.D.?](group-syllabus/why-phd.md) | Understanding the purpose and value of doctoral studies | -| [Funding](group-syllabus/funding.md) | Information about funding sources and expectations | -| [Working with me](group-syllabus/working-with-me.md) | Expectations and guidelines for advisor-student relationship | -| [Doing research](group-syllabus/doing-research.md) | Approaches to computational physics research | -| [Publishing](group-syllabus/publishing.md) | Guidelines for academic publishing | -| [When and where of working](group-syllabus/when-where-working.md) | Expectations about work schedule and location | -| [Going to conferences](group-syllabus/going-to-conferences.md) | How to prepare for and attend academic conferences | -| [Giving talks](group-syllabus/giving-talks.md) | Guidelines for effective research presentations | -| [Challenges](group-syllabus/challenges.md) | Common challenges and how to address them | - -## ✍️ Papers and Writing - -| Resource | Description | -|----------|-------------| -| [Academic writing](group-syllabus/improving-your-writing.md) | Improving your scientific writing skills | -| [Formatting your documents](group-syllabus/formatting.md) | Standards for document formatting | -| [Making figures](group-syllabus/figures.md) | Creating effective scientific figures | -| [Responding to reviewers](group-syllabus/responding-to-reviewers.md) | How to handle peer review feedback | - -## 💻 Details - -| Resource | Description | -|----------|-------------| -| [Undergraduate specifics](group-syllabus/undergraduate-specifics.md) | Information specific to undergraduate researchers | -| [Available computers](group-syllabus/computers.md) | Computing resources available to group members | -| [Whose hardware is this, anyway?](group-syllabus/hardware.md) | Hardware ownership and policies | - -## 📝 Templates - -| Template | Description | -|----------|-------------| -| [For papers](templates/paper) | Templates for academic papers | -| [For responses to paper reviews](templates/paper_rebuttal) | Templates for responding to reviewers | -| [For figures](templates/paper/figures) | Templates for creating figures | -| [For talks](templates/talks) | Templates for presentations | - -## 🤝 Contributing - -This repository is designed to be collaborative. Current and former students are encouraged to contribute improvements, corrections, and additions based on their experiences. - -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to suggest changes or add content. - -## 👏 Acknowledgements - -Parts of this are borrowed, heavily edited, from the Ph.D. syllabi of [Eric Gilbert](https://docs.google.com/document/d/11D3kHElzS2HQxTwPqcaTnU5HCJ8WGE5brTXI4KLf4dM) and Mor Maaman. - -## 📄 License - -[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) - Creative Commons Attribution-NonCommercial 4.0 International +CC BY-NC 4.0