User Tools

Site Tools


bdoc:kernstyle

TODO of the person who was going to convert the manual into a book

  • maybe spell out “config” to “configuration” as appropriate
  • Use American versus British spelling
  • not critical, but for later consider cleaning out some use of “there” and rewrite to not be so passive.
  • make sure use of \elink shows URL in printed book
  • get rid of many references of “Red Hat” – too platform specific?
  • remove references to names, like “Dan Langille shared …” just put their names in credits for book
  • don't refer to very old software by specific version such as “Red Hat 7” or FreeBSD 4.9 because is too old to put in book. It may be relevant, but may be confusing. Maybe just remove the version number if applicable.
  • maybe fine, but discuss point-of-view: don't use personal “I” or possessive “my” unless that is consistent style for book.
  • replace “32 bit” and “64 bit” with “32-bit” and “64-bit” respectively.
  • It seems like more popular style standard be consistent with “Note” and “NOTE”. maybe use tex header for this
  • get rid of redundant or noisy exclamation marks
  • style for “ctl-alt-del” and “ctl-d”? and be consistent with formatting
  • be consistent for case for ext3, ext2, EXT3, or EXT2.
  • fix spelling of “inspite” in source and in docs (maybe use “regardless in one place where I already changed to “in spite”
  • be consistent with software names, like postgres, postgresql, PostreSQL and others
  • instead of using whitehouse for examples, use example.org (as that is defined for that usage); also check other hostnames and maybe IPs and networks
  • use section numbers and cross reference by section number or page number no underlining in book (this is not the web :)
  • some big gaps between paragraphs or between section headers and paragraphs – due to tex – adjust as necessary to look nice
  • don't include the GPL and LGPL in book. This will save 19 (A4) pages. For 6×9 book this will save 30 pages. (Keep GFDL though.)
  • many index items are too long
  • appendices not listed as appendix
  • some how consolidate indexes into one? on 6×9, the indexes are over 30 pages
  • don't refer to some website without including URL also (such as “this FreeBSD Diary article”)
  • get rid of (R) trademark symbols – only use on first use; for example don't put on the RPM Packaging FAQ
  • split up very long paragraphs, such as “As mentioned above, you will need …” (on my page 783).
  • use smaller font or split up long lines (especially from console output which is wider than printed page)
  • don't assume all BSD is “FreeBSD”
  • don't assume all “kernel” is Linux. If it is Linux, be clear.
bdoc/kernstyle.txt · Last modified: 2010/03/11 17:06 by kern