Differences

This shows you the differences between two versions of the page.

--- tutorials:writing [2022/06/17 11:47] – [Files] chkuo
+++ tutorials:writing [2023/08/20 23:26] (current) – removed chkuo
@@ Line 1: / Line 1: @@
-====== Writing ======
-Guidelines for scientific writing that Chih-Horng Kuo (chk@gate.sinica.edu.tw) developed for our group members. Suggestions are welcome.
-===== General =====
-  * Writing is possibly the most important, yet also the most challenging part, of our work
-  * Start early
-  * Find the time of day that works best for you, establish a writing routing, then stick to it.
-    * Oftentimes you may feel like hitting a wall that you cannot break through when you stare at the blank page. However, it is critical that you spend the time and struggle, rather than distract yourself with other tasks as a way out. The struggle that you endure is a natural (and likely unavoidable) part of the process. You just have to devote effort to make writing happen (yes, it will, just not so easy; see all the successful cases in the lab).
-  * Talking to people helps (a lot)
-===== Files =====
-  * Backup
-    * Establish an automatic backup plan
-    * Mac: Time Machine
-    * Linux: rsync scripts
-  * Naming and version control
-    * File names
-      * Do: short and informative. Include information such as project id, keyword (e.g. manuscript, report, keyword of figure/table), version or date
-      * Avoid: long names that are difficult to read (e.g., full title of the manuscript)
-      * Avoid: short names that are not informative (e.g., manuscript.docx, figure1.ai)
-      * Avoid: space or special characters
-      * Avoid: "xxx_final.docx", "xxx_final_revised.docx", "xxx_final_revised_typofixed.docx", etc
-    * Versioning
-      * Version number should be the last part of the file name; two digits should be sufficient
-      * If multiple people are involved in the project, add initials
-      * Recommended: In early versions of manuscript drafts, add a short section in the beginning of the document to explain the major changes made
-    * Project progress report
-      * In the beginning of the document, include name (who prepared this report), date (when was it prepared), project id (to be matched with related record), directory of relevant files (on lab servers for people to get raw data files if needed)
-    * Branching and merging
-      * When multiple people are involved, branches may be created for each person to work on a different part
-      * It is important that everyone agree with the leader on when and how to merge the branches
-      * Example
-        * For project "agro38", start the main manuscript file as "agro38_ms_v01.docx"
-          * ABC then saved the file as "agro38_ms_v02_ABC.docx" to work on Introduction
-          * DEF creates "agro38_ms_v02_DEF.docx" to work on Materials and Methods
-          * GHI creates "agro38_ms_v02_GHI.docx" to work on Figure Legend.
-        * ABC being the project leader, should be responsible to set the deadline, collect the files, then merge and create ''agro38_ms_v03.docx'' as the starting point for the next iteration.
-    * Figure/table files
-      * Before finalizing the order, use names without fig/table number and with a keyword (e.g., "fig_phylogeny_v02.ai", table_accession_v05.xlsx")
-      * After finalizing the order, put all early versions into a separate folder (e.g., "figure_stage1"), then add figure/table numbers to the file names (e.g., "fig1_phylogeny_v15.ai")
-      * If the order changed, put the previous versions into another separate folder (e.g., "figure_stage2"), then update the figure/table numbers (e.g., "fig3_phylogeny_v16.ai")
-  * Tracking changes
-    * For Word files: better to use the build-in function ''Track Changes''; possible to use the ''Compare Documents'' functions later.
-    * For Google Documents: all changes are automatically tracked. Manually name and download the major versions.
-  * Working with collaborators
-    * Discuss and setup a workflow
-    * Avoid email files as attachments; use a file server or file sharing service (e.g., Google Drive or Drop Box) instead.
-    * Pros and cons of setting up a file server vs. using a commercial service.
-  * File directory structure
-    * Make it easy to identify the parts that need to be included in backup
-    * Example for personal desktops/laptops
-    * Example for shared servers
-===== References =====
-  * Zotero ([[https://www.zotero.org/]]) is recommended
-  * Download and account setup
-    * Syncing
-  * Importing references
-    * Zotero Connector: integration with browsers
-    * Add by DOI or other identifiers
-    * Manual entry
-  * Library management
-    * Folders and subfolders
-      * Recommended; easy to use, one entry can be in multiple folders
-    * Tags
-      * Automatically imported, may be edited. May take too much effort to curate.
-    * Curation [**IMPORTANT**]
-      * After the initial import, the style likely would not be consistent across different entries
-      * For the references that will be used in the same document, curate all entries to maintain the consistency
-      * Title capitalization
-      * Journal full name (the "Publication" field) and abbreviated name (the "Journal Abbr" file); see the NLM Catalog ([[https://www.ncbi.nlm.nih.gov/nlmcatalog/journals]])
-      * Is the publication year correct? (first published online vs. formal reference info)
-      * Is the page number missing? (particularly for online-only journals)
-      * Add your own notes?
-  * Style Manager
-    * Remove the default ones that you do not need
-    * Add additional ones as needed
-  * Integration with Word or Google Documents
-    * Communicate well with your collaborators; avoid mixing different libraries in the same document
-    * Backup to protect against file corruption
-    * Double check everything after formatting