User Tools

Site Tools


projects:workgroups:notes_on_writing_text_for_the_book

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
projects:workgroups:notes_on_writing_text_for_the_book [2019/06/03 09:11]
schuemie
projects:workgroups:notes_on_writing_text_for_the_book [2019/08/07 14:02]
schuemie
Line 15: Line 15:
 ===== Keep in mind ===== ===== Keep in mind =====
  
-  * Hyperlinks should show the actual URL, so that a printed copy would still have a readable link.+  ​* Abbreviations should be re-defined in each chapter. So yes, the first time you mention CDM in your chapter it should be CDM (Common Data Model). 
 + 
 +  * Table names should be all-caps, so OBSERVATION_PERIOD. Field names should be lower case, so observation_period_id.  
 + 
 +  * When quoting, use "​double quotes"​. 
 + 
 +  ​* Hyperlinks should show the actual URL, so that a printed copy would still have a readable link. To avoid formatting issues, it might be best to add the URL as a footnote. Use URLs sparingly.
  
   * Tables and figures should be designed with small screens in mind.   * Tables and figures should be designed with small screens in mind.
 +
 +  * The maximum section depth is 3, so for example section 2.3.4. You can finagle a 4th level by using bold headers (not numbered).
  
   * Keep filename extensions in lower case, so '​figure.png',​ not '​figure.PNG'​.   * Keep filename extensions in lower case, so '​figure.png',​ not '​figure.PNG'​.
Line 137: Line 145:
    This done through the [FeatureExtraction](https://​ohdsi.github.io/​FeatureExtraction/​) package.    This done through the [FeatureExtraction](https://​ohdsi.github.io/​FeatureExtraction/​) package.
  
 +===== Adding index terms =====
 +
 +This section describes how to add index terms that will appear in the back-of-the-book index. ​
 +
 +Note: This is only relevant for those folks that have been appointed as indexers. Please do not try to add index terms if you are not an indexer.
 +
 +To identify a point in the book where a certain term is discussed, just add
 +
 +''​\index{your term here}''​
 +
 +to the Rmd file at the appropriate position. This markup will not be rendered in the HTML or PDF at that location, and will only be used to create the index entry in the back of the book.
 +
 +Most index terms should simply start with a lower case, unless it's a proper noun. Only mark the term if the page is really about the term, not if the page just mentions the word. Ask yourself: if I were to look this term up in the back-of-the-book index, is this the page I would want to read?
 +
 +Below are examples of index entries:
  
 +{{:​projects:​workgroups:​index.png|}}
  
projects/workgroups/notes_on_writing_text_for_the_book.txt · Last modified: 2019/08/07 14:02 by schuemie