User Tools
appendix:guidebook_authoring
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
appendix:guidebook_authoring [2018/08/15 15:50] jguerin |
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, | + | * easy to locate |
| - | * coverage of the broadest possible set of topics | + | * coverage of the broadest possible set of topics |
| While the guidebook is most likely going to originate out of the efforts of UT Martin professors/ | While the guidebook is most likely going to originate out of the efforts of UT Martin professors/ | ||
| 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 | + | * Terseness |
| * 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 67: | Line 67: | ||
| ==== Comment Your Edits ==== | ==== Comment Your Edits ==== | ||
| * Even the first author occasionally forgets. Don't be like him. Comment your edits. | * Even the first author occasionally forgets. Don't be like him. Comment your edits. | ||
| + | |||
| + | ==== Formatting Tips ==== | ||
| + | * Make use of single '' | ||
| + | * Use italics mode '' | ||
| + | * Hack mathematical expressions with tags (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., '' | ||
| + | * 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.1534366249.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
