UT Martin Competitive Programming Guidebook

User Tools

Site Tools

Trace:
appendix:guidebook_authoring

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
appendix:guidebook_authoring [2018/08/15 15:50]
jguerin Added notes on consistency. 		appendix:guidebook_authoring [2018/08/15 16:22] (current)
kericson [Terse is Almost Always Better] - better?
Line 12: Line 12:
   * consistency in terms of structure (both overall organization and of page contents),   * consistency in terms of structure (both overall organization and of page contents),
   * consistency in terms of tone (as though the entire endavor was written from the perspective of a single author),   * consistency in terms of tone (as though the entire endavor was written from the perspective of a single author),
-  * easy to locte information, driven primarily by working examples, +  * easy to locate information, driven primarily by working examples, 
-  * coverage of the broadest possible set of topics reltaed to the general field of computer science.+  * coverage of the broadest possible set of topics related to the general field of computer science.
  
 While the guidebook is most likely going to originate out of the efforts of UT Martin professors/coaches and students, we hope to eventually have additional volunteers assisting with guidebook development. While the guidebook is most likely going to originate out of the efforts of UT Martin professors/coaches and students, we hope to eventually have additional volunteers assisting with guidebook development.
Line 48: Line 48:
 ==== Terse is Almost Always Better ==== ==== Terse is Almost Always Better ====
   * This page may be the worst example of this principle.   * This page may be the worst example of this principle.
-    * Verbosity in this page is sacrifice to produce consistency elsewhere.+    * Terseness in this page is sacrificed to produce consistency elsewhere.
   * Keep editing to say everything in a few short statements.   * Keep editing to say everything in a few short statements.
   * Pull content into auxiliary pages as necessary, make liberal use of links.   * Pull content into auxiliary pages as necessary, make liberal use of links.
Line 66: Line 66:
  
 ==== Comment Your Edits ==== ==== Comment Your Edits ====
 +  * Even the first author occasionally forgets. Don't be like him. Comment your edits.
  
 +==== Formatting Tips ====
 +  * Make use of single ''%%''%%'' quotes for all source in paragraph, ''<code>'' or ''<file>'' tags where appropriate.
 +  * Use italics mode ''%%//%%'' for emphasis, highlighting industry terms, and variable names as a cheap (LaTeX) math mode replacement.
 +  * Hack mathematical expressions with tags (e.g., ''%%<sup></sup>%%''), special symbols from the editor (e.g., ξ, ∑).
 +    * Much of what we need to express for guidebook purposes can be written well (and look quite good on most browsers) with some creative hacking.
 +    * Mathematics should be presented as we would typeset it in LaTeX.
 +  * If examples emulate a shell, make it clear with symbols.
 +    *  E.g., ''%%>>>%%'' for Python, ''$'' for arbitrary Linux shells (e.g., Bash).
 +  * Present results as they would look in practice.
 +
 +=== C++ Conventions ===
 +
 +=== Python3 Conventions ===
 +  * Avoid the shebang line. Overall it will net a significant savings.
 +  * In Python, use single quotes for characters, double for multi-character strings.
 +    * No, this is not required by the language, but keeps examples consistent where they otherwise may not be.
  
appendix/guidebook_authoring.1534366213.txt.gz · Last modified: 2018/08/15 15:50 by jguerin

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
CC Attribution-Noncommercial-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki