#25 Needs glossary

#26 Intro / guide layout: Grammar / diction
#27 Guide layout references section that does not exist
#28 Help section could benefit frmo copyediting
Reviewed by: Richard Lowe <[email protected]>
Reviewed by: Robert Mustacchi <[email protected]>

Author: jblachly

Makefile

@@ -42,11 +42,13 @@ IMAGE_FILES = \
 FILES = \
 	intro \
 	workflow \
+	guidelines \
 	layout \
 	anatomy \
 	debugging \
 	integrating \
 	help \
+	glossary \
 	license
 
 OUTDIR =	output

glossary

@@ -0,0 +1,37 @@
+# Appendix: Glossary of Terms
+
+**CTF**
+Compact C Type Format. Assists in debugging. See
+[ctf(4)](http://illumos.org/man/4/ctf).
+
+**CW**
+Compiler wrapper. Historical version of illumos were built with Sun Studio
+(see below). In order to transition to the `gcc` compiler, the compiler
+wrapper was developed to translate compiler flags from Sun Studio syntax
+to GCC syntax.
+
+**FMA**
+Fault management architecture.
+
+**Gate; illumos gate**
+Gate is old Sun Microsystems terminology for a software source-code repository.
+
+**Lint; linting**
+Using the `lint` tool to check for common programming errors.
+
+**ON**
+OS/Net (Operating system/Network) consolidation. In historical version of SunOS,
+OS and Net were separate software components. Now this term refers to the
+operating system as a whole. 
+
+**RTI**
+Request to Integrate. The final approval process needed for a change to become
+part of the illumos gate. See [Integrating Changes](./integrating.html).
+
+**Sun Studio**
+A compiler suite historically required to build illumos. As of 2016, dependency
+on Sun Studio has been eliminated with the exception of the `lint` tool.
+
+**UTS**
+Unix Time Sharing. This is a historical name for UNIX, and lives on in the
+source tree as the `uts/` directory, which houses the kernel.

guidelines

@@ -0,0 +1,6 @@
+# illumos Guidelines and Principles
+
+This section covers various core guidelines we have when working inside
+of the illumos gate. It also goes into detail about several of the
+guiding engineering principles that have brought this project from its
+time at Sun through to today.

help

@@ -8,16 +8,16 @@ and what to do if you find issues with this document.
 ## Additional Help with illumos
 
 If you have difficulty with building, are not sure what to do, or just have
-additional questsions, illumos has a broad community that is happy to help you
-out. There are a few different places that you can direct questions to:
+additional questsions, illumos has a friendly community that is happy to help
+you out. There are a few different places that you can direct questions:
 
   * Mailing Lists
-  * IRC
+  * Internet Relay Chat (IRC)
 
 ### illumos Mailing Lists
 
 illumos has several different mailing lists. When it comes to development, it
-has one catch all list and then several special interest lists. The general
+has one catchall list and several special interest lists. The general
 developer list is called 'developer'. There are currently three special interest
 lists that cover ZFS, DTrace, and Networking. If your question is related to
 development or use of one of those three technologies, then you should consider
@@ -31,14 +31,15 @@ development of illumos itself, then you should send mail to
 Generally speaking, you should avoid private mail asking for help. While a given
 individual may indeed know the most about your situation, they may not have as
 much time to address it as rapidly as you would like. Sending to the mailing
-list gives you access to as many people as possible who may be familiar. That
-said, if you are someone who is on that mailing list and you are not as familiar
-with a given issue, then do not feel compelled to reply. This helps us keep the
-signal to noise ratio healthy on the mailing lists.
+list gives you access to as many people as possible who may be familiar with
+your specific problem. That said, if you are someone who is on that mailing
+list and you are not as familiar with a given topic, then do not feel compelled
+to reply. This helps us keep the signal to noise ratio healthy on the mailing
+lists.
 
 If you want to raise some general discussion about the use of illumos that is
-not related to development activities, please send mail to the illumos discuss
-or a special interest list instead. The developer list is solely intended for
+not related to development activities, please send mail to the 'illumos-discuss'
+or a special interest list instead. The developer list is intended solely for
 development of illumos itself.
 
 If you have questions about how to do something in the context of a specific
@@ -48,25 +49,26 @@ day the members of the illumos community want to make sure that your problem
 gets addressed and will help redirect you to the appropriate place.
 
 For the full set of illumos lists, as well as, various distribution-specific
-lists, please see XXX[%d]. 
+lists, please see
+[The illumos wiki Mailing list page](http://wiki.illumos.org/display/illumos/illumos+Mailing+Lists). 
 
-### IRC
+### Internet Relay Chat (IRC)
 
 The illumos community maintains an active IRC channel in `#illumos` on
 `irc.freenode.net`. This room is used for general discussion, answering
-technical questions about illumos, and providing assistence with debugging and
-solving problems with illumos. Please leave yourself logged in for some time.
+technical questions about illumos, and providing assistance with debugging and
+illumos problem-solving. *Please leave yourself logged in for some time* --
 Questions are not always immediately answered, but folks do commonly look for
 unanswered questions and try to help.
 
-If you are having issues using a specific distribution, for example, how do you
-install a specific piece of software, you can get the most help by using a
+If you are having issues using a specific distribution (for example, "how do I
+install a specific piece of software?"), you can get the most help by using a
 distribution specific IRC channel which are generally also found on
 `irc.freenode.net`.
 
 ### Help Us Help You
 
-In either case, please remember that people can only help you if you provide
+In any case, please remember that people can only help you if you provide
 them enough information. If you have a program dumping core or the operating
 system is panicking, then please find some way to make that available. If you
 have questions about code that you have written consider making a webrev of your

intro

@@ -9,12 +9,21 @@ guide will help you in enhancing and fixing illumos.
 
 ## What is illumos?
 
-illumos is a consolidation of software that forms the core of an Operating
+illumos is a collection of software that forms the core of an Operating
 System. It includes the kernel, device drivers, core system libraries, and
-utilities. It is the home of many technologies include ZFS, DTrace, Zones, ctf,
+utilities. Conceptually, the illumos idea of "the operating system"
+lies between something like Linux (which is the kernel only; all of userspace
+is delivered by vendors in a "distribution") and the BSD family of operating
+systems, which are packaged as a complete unit (kernel, core libraries,
+userspace utilities, and even end-user software packages).
+
+illumos is the home of many technologies including ZFS, DTrace, Zones, ctf,
 FMA, and more. We pride ourselves on having a stable, highly observable, and
-technologically different system. In addition, illumos traces it roots back
-through Sun Microsystems to the original releases of `UNIX` and `BSD`.
+technologically different system. Finally, illumos has a proud engineering
+heritage, tracing it roots back through Sun Microsystems to the original
+releases of `UNIX` and `BSD`.
+
+
 
 ## Guide Layout
 
@@ -30,9 +39,9 @@ This guide is broken into the following sections:
 
   * illumos Guidelines and Principles
 
-  This section covers various core guidelines we have when working inside of
+  This section covers various core guidelines we have when working inside the 
   illumos gate. It also goes into detail about several of the guiding
-  engineering principles that have been guided this project from its time at Sun
+  engineering principles that have brought this project from its time at Sun
   through to today.
 
 
@@ -74,31 +83,47 @@ This guide is broken into the following sections:
   on working with illumos, this document, or anything else that might come up.
 
 
+  * Appendix: Glossary
+
+  This section provides a reference to acronyms and other terms that are
+  used in this guide, and either unique to illumos (and related operating
+  systems), or that may be unfamiliar to those who have not previously
+  done UNIX systems development.
+
   * Appendix: Documentation License
 
 ## Conventions
 
-The following describes the current typographical conventions in use in this
-document.
+The following section describes the current typographical conventions used
+in this document.
+
+### Commands
 
-When text begins as follows, it indicates that it's being run as a normal user
-shell:
+Fixed-width text beginning with a dollar sign indicates a shell command that
+should be run as a normal user:
 
 ```
 $
 ```
 
-When text begins as follows, it indicates that it is being run as a super-user's
-shell:
+Fixed-width text beginning with a hash mark indicates a shell command to be
+executed by the super-user's shell:
 
 ```
 #
 ```
 
-When text is formatted as `name(number)` that indicates that it is referring to
-the command with the name `name`, and in the section described by number. For
-example, read(2) refers to the read function in section 2 of the manual page,
-while ctf(4), would refer to the manual page on the CTF file format which is in
-section 4,  and finally connect(3SOCKET), refers to the connect function that's
-found in the `3SOCKET` section of the manual, which are functions that are a
-part of the library, `libsocket`.
+### Manual Pages
+
+When you see text formatted as `name(number)`, that indicates a reference to
+the command named `name` in section `number` of the manual. When they appear
+in this developer's guide, there should be a hyperlink to the appropriate
+manual page. For example, read(2) refers to the `read()` function
+in section 2 of the manual, while ctf(4) refers to the manual page on the CTF
+file format, which is section 4. Manual sections may have a sub-descriptor
+after the number: connect(3SOCKET) describes the `connect()` function that
+can be found in the `3SOCKET` section of the manual; this section describes
+functions that are a part of the `libsocket` library.
+
+See the subsection [Manual Pages](anatomy.html#manual-pages) in the Components
+section for more information about man pages, including the numbering scheme.