Welcome to the EtherPad notes for the next print edition of the FreeBSD handbook!
Please refer to this document for background info:
- some sub-sections are unnecessarily deep; do we want to place a cap on levels and reorganize accordingly?
- regarding trademarks, should we adopt the policy of "first mention" in the Copyright section, then no longer needed in rest of Handbook?
- not including Appendix D reduces Handbook from 1491 to 954 pages
bcr thinks that we agree that this has little use in a printed book, not even in an electronic edition
- Gavin agrees - not necessary at all to have PGP keys in printed book especially since PGP keys are somewhat volatile.
Instead, just replace them with a pointer in the book to where they can be found online
- all sections should begin with a Synopsis/Introduction; should this be a subsection or just the introductory material after the title of the section?
- all sections (where applicable) should be divided between a Quick Start and Advanced topics
1. Should published version remove authors' names from section and include in Acknowledgements (should this also be for online edition?
- currently this is inconsistent, some chapters have authors names attached, some do not
- this info should be moved to Acknowledgements section in preface; will require review of svn history--this task should be divided and should be separate task from content creation
- Acknowledgements should be a list of names with larger contributions associated with author; should also thank Editors
- Acknowledgement section will most likely need to be divided due to number of contributors and size of contributions
2. Some sub-sections are unnecessarily deep; do we want to place a cap on levels and reorganize accordingly?
- deepest is 6 levels, with unnecessary sections (section names with no content)
- our policy will be to recommend 3 and put a hard cap at 4
3. Regarding trademarks, should we adopt the policy of "first mention" in the Copyright section, then no longer needed in rest of Handbook?
- currently the Handbook is not consistent in this regard
- we need to either give proper attribution once in Preface and not repeat in rest of work or we need to find every term that needs a R or TM and make sure it has it
- we think current best practice is first occurrence in the Table of Contents, in headlines (Preface?), and on the first occurrence in text of work.
- Dru will send email to Foundation to ask their lawyer which is correct practice at this time (10 years ago, it was reference every time)
4. What is the official use of bold?
- Applications with the <application> tag get bolded
5. Should Synopsis/Introduction be a subsection or just the introductory material after the title of the section?
- Terminology should be introduced as it is used and also be placed in a glossary at end of work.
- Sections should have the following headings: Introduction, Quick Start, Detail (title(s) will vary by content), Troubleshooting, Additional Resources (note that Introduction is not actually a heading, but an introductory paragraph)
- Detail sections will have their own synopsis
6. What are our capitalization rules for titles?
- http://grammar.quickanddirtytips.com/capitalizing-titles.aspx 2nd point, except markup (e.g. for commands and files) are ignored
7. What belongs on the cheatsheet of formatting stuff for writers: title rules, when to include manpage number, how to setup a section, rules on subsections, not having titles with no content other than more subsections, when to use index tags, adding tags for older versions that won't be in the book, rule for using acronyms (e.g. only first use is spelled out), format of hyphenated words, reword titles with "?", figure naming, an or a before N, etc.
- Include http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html#writing-style-guide
- and http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/xml-markup-docbook.html#AEN1388
- how to properly tag figures needs to be added to FDP
- recommend that authors run igor themselves, fix as they think best, and then commit or send their patch
- always build the doc with your changes before committing
8. What should the format for each section be (for template purposes)? e.g. Synopsis/Introduction, Basic Tasks, Advanced Tasks, Troubleshooting, others?
- see #5