meta data for this page
  •  

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
general:dokuwiki:how2document [2022/01/07 14:41] – [Project report] ingogeneral:dokuwiki:how2document [2022/12/20 09:30] (current) – [References] ingo
Line 1: Line 1:
-====== Project documentation ====== 
-===== Necessary information ===== 
-Project documentation is essential when working in a scientific environment. Figure {{ref>docucont}} is the result of a brain storming session that tried to highlight the main information that should be provided in a project documentation. Note, this list is not necessarily exhaustive.  
- 
-<figure docucont> 
-{{:general:dokuwiki:docucontent.png?400|}} 
-<caption><fs 0.8em>An unordered list of information that should find its way into a proper project documentation. 
-</fs></caption> 
-</figure>  
- 
- 
 ====== Lab protocols ====== ====== Lab protocols ======
 Most practical modules in your curriculum require that you write a lab protocol at the end of your project. This lab protocol is your proof of achievement, and thus must be taken seriously, independent of whether it is graded or not. Please find below some information that should give you an idea of what to consider when writing a protocol. Most practical modules in your curriculum require that you write a lab protocol at the end of your project. This lab protocol is your proof of achievement, and thus must be taken seriously, independent of whether it is graded or not. Please find below some information that should give you an idea of what to consider when writing a protocol.
  
-<WRAP important><fs 1.5em>There is a difference between a lab protocol, and the daily documentation of your work in the WIKI. If we tell you that you can hand in your WIKI as a lab protocol, we expect that you write your WIKI such that it adheres to the guidelines listed below</fs></WRAP>+<WRAP important><fs 1.5em>There is a difference between a lab protocol, and the daily documentation of your work in the WIKI. You can write, in principle, a lab protocol as a set of WIKI pages, but then we expect that it adheres to the guidelines listed below</fs></WRAP>
 ===== Objective ===== ===== Objective =====
 Before writing a lab protocol, you should ask yourself not only //why// your are writing a lab protocol, but much more //what you want to achieve// with the lab protocol. The answer is considerably simple: You write the lab protocol for  Before writing a lab protocol, you should ask yourself not only //why// your are writing a lab protocol, but much more //what you want to achieve// with the lab protocol. The answer is considerably simple: You write the lab protocol for 
   * yourself. It should bring you in the position to easily repeat your analysis - or parts of it - somewhen in the future, and probably at a time point where you can no longer do it from the back of your head((since you have forgotten about all the details))   * yourself. It should bring you in the position to easily repeat your analysis - or parts of it - somewhen in the future, and probably at a time point where you can no longer do it from the back of your head((since you have forgotten about all the details))
-  * for any other person that comes after you, such that this person has a chance to understand<WRAP>+  * for any other person that comes after you, such that this person has a chance to understand
     * what you did     * what you did
     * why you did it      * why you did it 
     * and how you did it     * and how you did it
-In essence, with the help of your protocol, any person should be able to quickly reproduce your analysis</WRAP> +<wrap important></wrap>With the help of your protocol, any person should be able to quickly reproduce your analysis. If you keep this objective in mind, then you should already have a good idea of how to write a protocol.
-If you keep this objective in mind, then you should already have a good idea of how to write a protocol.+
  
  
Line 36: Line 24:
 Follow this [[https://www.thoughtco.com/how-to-write-a-lab-report-606052|LINK]] to get some additional ideas of how to write a good report Follow this [[https://www.thoughtco.com/how-to-write-a-lab-report-606052|LINK]] to get some additional ideas of how to write a good report
  
-<fs 1.5em><wrap tip>It is a good idea to carefully read the [[howto:scientific_essay|Guidelines]] of how to write scientific text</wrap></fs>+<fs 1.5em><wrap tip>It is a good idea to carefully read the guidelines {{ :general:documentation:how_to_write_scientific_text.pdf |How to write scientific text}}</wrap></fs>
 ===== Some additional points to consider ===== ===== Some additional points to consider =====
  
 Below, we have compiled a collection of points that you should check before writing a protocol, and afterwards as well Below, we have compiled a collection of points that you should check before writing a protocol, and afterwards as well
-  * Try sticking to the standard structure<WRAP> +==== Structure of the protocol ===== 
-      * Introduction +Try sticking to the standard structure<WRAP> 
-      * Material & Methods +   * Introduction 
-      * Results +   * Material & Methods 
-      * Discussion +   * Results 
-      * Bibliography +   * Discussion 
-<WRAP important>Don't mix up the contents of the main sections! In particular, there is always the danger to write results in the discussion section, or vice versa!</WRAP></WRAP> +   * References 
-  * Figures +<WRAP important>Don't mix up the contents of the main sections! In particular, there is always the danger to write results in the discussion section, or vice versa! Likewise, people tend to write results into the methods section. Simply don't do it...</WRAP></WRAP> 
-      * each figure has  + 
-        * a figure number. Figure numbers must occur in the correct order in the main text +==== Figures ==== 
-        * a short, informative title  +<wrap important></wrap>Before inserting a figure, think about what it should tell the reader, and then design it accordingly. In particular think about the final image size when drawing it. Figures for print are typically either 80 mm (single column) or 160 mm (two columns) wide.((it is not a good idea to draw figures in any size first and later re-scale them. This will result in font sizes and line weights that to be different for each figure!))  
-        * a description that reflects the message of the figure. Make sure that the figure description does not end up in the main text + 
-      * each figure should be interpretable on its own. It is generally a bad idea to refer to other figures (other than supplementary figures) in the figure caption  +Each figure...  
-      * Screenshots als Abbildungen sind ok, allerdings muss die Bildauflösung ausreichend hoch sein. Verpixelte Abbildungen haben in einem Protokoll nichts zu suchen +   * has a figure number. And figures have to be numbered in the order they are mentioned in the text 
-  * Tables +   * has to be mentioned in the text 
-    * Each table has an informative title. Table columns can be explained in the table footnotes +   * has a short, informative title  
-  * Methods +   * has a description that reflects the message of the figure. Make sure that the figure description does not end up in the main text 
-    * provide references for the programs you use, the URL from where you have downloaded it, and <wrap important>provide the program version together with the relevant parameter settings</wrap> +   * should be interpretable on its own. It is generally not optimal to refer to other figures (other than supplementary figures) in the figure caption  
-  * References + 
-    * Wikipedia cannot serve as a reference for scientific text, because it is a source of information that is subject to change over time +<wrap important></wrap>Watch out for the following 
-    * Make sure that references in the text, and your bibliography is correctly and consistently formatted +   * Screenshots as figures can be ok, but only when the image quality is sufficiently high.  
-  * Abbreviations +   * make sure that the font and the font size is uniform across the figures. Text must be <fs 0.1 em>sufficiently</fs> large to ease the access to the figure content. 
-    * Abbreviations, that cannot safely be considered common knowledge, have to be explicitly introduced. For example you can write "We used the //Quest for Orthologs// (QfO) set of reference proteomes... +   * avoid figures landscape format  
-    * Species names have to be given in full length, before you start abbreviating them. For example you should write: "(...) we extracted all ribosome biogenesis factors from yeast (//Saccharomyces cerevisiae//)". Later in the text, you can then abbreviate the species name to //S. cerevisiae//. + 
-  * Spelling +==== Tables ==== 
-    * Most editors provide a spell checker. Make sure to use this! +Like with figures, think about the information that should be provided with a table 
-  * Headings +  * tables have to be successively numbered according to the order they are referred to in the text 
-    * Headings should be concise and informative. Something like ‘Getting an idea (of) how to use HaMStR…’ should be avoided. This could be reformulated to ‘Establishing the HaMStR Workflow for …' +  * each table has to be mentioned in the text 
-  * Miscellaneous  +  * each table has an informative title. Table columns can be explained in the table footnotes 
-    * Use standards whenever possible +  * avoid landscape tables 
-    * briefly introduce relevant methods such that you - as well as any other person - comes into the position to understand what kind of analysis you are actually doing. +  * avoid tables that extend over more than one page. Consider placing large tables into the supplement 
-    * Avoid lab jargon. For example, //to blast// is not the appropriate verb for //performing a Blast search// +  * don't use vertical lines to delimit table columns. Horizontal lines to delimit rows are ok, though 
-    * Avoid group-internal abbreviations such as //DROME// as an abbreviation for //Drosophila melanogaster//+ 
 +==== Methods ==== 
 +  * provide references for the programs you use, the URL from where you have downloaded it, and <wrap important>provide the program version together with the relevant parameter settings</wrap> 
 + 
 +==== References ==== 
 +<wrap important></wrap>Remember why we use references? This is because we have to back up each statement in a scientific text with supporting evidences. These can be either previously published **and** peer-reviewed literature, or own data. In either case, the supporting information must be invariant with time. Thus, **Wikipedia cannot serve as a reference for scientific text** for several reasons. One of the most important ones is that article contents are subject to change over time! 
 +   * Make sure that references in the text, and your bibliography is correctly and consistently formatted. We prefer the //author, year// format for in-text citations over numbers. 
 +You can read more about how to cite in this document provided by the University of Cologne (in German only): [[http://uni-koeln.de/phil-fak/storyline2/story_content/external_files/Handout_%C3%9Cberpr%C3%BCfbarkeit.pdf|Handout_Ueberpruefbarkeit]]  
 +==== Abbreviations ==== 
 +Abbreviations, that cannot safely be considered common knowledge, have to be explicitly introduced.  
 +  * For example you can write "We used the //Quest for Orthologs// (QfO) set of reference proteomes... 
 +  * Species names have to be given in full length, before you start abbreviating them. For example you should write: "(...) we extracted all ribosome biogenesis factors from yeast (//Saccharomyces cerevisiae//)". Later in the text, you can then abbreviate the species name to //S. cerevisiae//. 
 + 
 +==== Spelling ==== 
 +Most editors provide a spell checker. Make sure to use this! 
 + 
 +==== Headings ==== 
 +Headings should be concise and informative. Something like ‘Getting an idea (of) how to use HaMStR…’ should be avoided. This could be reformulated to ‘Establishing the HaMStR Workflow for …' 
 + 
 +==== Miscellaneous ====  
 +  * Use standards whenever possible 
 +  * briefly introduce relevant methods such that you - as well as any other person - comes into the position to understand what kind of analysis you are actually doing. 
 +  * Avoid lab jargon. For example, //to blast// is not the appropriate verb for //performing a Blast search// or even better for //searching for significantly similar sequences in a database using the Blast algorithm// 
 +  * Avoid group-internal abbreviations such as //DROME// as an abbreviation for //Drosophila melanogaster//
   * Datensets   * Datensets
     * Introduce data sets that you use in your analysis in the Materials section, and make sure to explain where the data is located     * Introduce data sets that you use in your analysis in the Materials section, and make sure to explain where the data is located
  
------ 
- 
-You will find some general guidelines for writing a project report, or in general scientific text here 
-  * [[https://www.thoughtco.com/how-to-write-a-lab-report-606052|How to write a Labreport]] 
-  * {{ :general:documentation:how_to_write_scientific_text.pdf |How to write scientific text}}