DOCS-140 review

Author: miketheman

source/administration/configuration.rst

@@ -16,8 +16,8 @@ and settings, this document primarily uses the configuration file
 interface. If you run MongoDB using a control script or packaged for
 your operating system, you likely already have a configuration file
 located at ``/etc/mogondb.conf``. Confirm this by checking the content
-of the ``/etc/init.d/mongodb`` or ``/etc/rc.d/mongodb`` script to
-insure that the :term:`control scripts <control script>` starts the
+of the ``/etc/init.d/mongod`` or ``/etc/rc.d/mongod`` script to
+insure that the :term:`control scripts <control script>` start the
 :program:`mongod` with the appropriate configuration file (see below.)
 
 To start MongoDB instance using this configuration issue a command in
@@ -202,6 +202,8 @@ different configurations. The config servers stores the cluster's
 metadata, while the cluster distributes data among one or more
 shard servers.
 
+TODO: Make a point that the config servers are not a replica set?
+
 To set up one or three "config server" instances as :ref:`normal
 <base-config>` :program:`mongod` instances, and then add the following
 configuration option:
@@ -345,3 +347,5 @@ needed:
    addition to tools such as :program:`iostat`, :program:`vmstat`, or
    :program:`top` to provide insight into the state of the system
    in context of the log.
+
+TODO: This setting doesn't actually work as explained. See here: https://jira.mongodb.org/browse/CS-2260?focusedCommentId=86579&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-86579

source/reference/configuration-options.rst

@@ -13,8 +13,8 @@ Administrators and users can control :program:`mongod` or
 configuration file.
 
 While both methods are functionally equivalent and all settings are
-similar, The configuration file method is preferable and if you
-installed from a package and starting MongoDB using your system's
+similar, the configuration file method is preferable. If you
+installed from a package and have started MongoDB using your system's
 :term:`control script`, you're already using a configuration file.
 
 To start :program:`mongod` or :program:`mongos` using a config file,
@@ -27,12 +27,16 @@ use one of the following forms:
    mongos --config /srv/mongodb/mongos.conf
    mongos -f /srv/mongodb/mongos.conf
 
-Declare All settings in this file using the following form:
+Declare all settings in this file using the following form:
 
 .. code-block:: sh
 
    <setting> = <value>
 
+TODO: This is not completely accurate. Some settings are <setting>=<value> (no spacing). 
+Ref here: https://github.com/mongodb/mongo/blob/master/rpm/mongod.conf
+This is probably something we should standardize on with no spaces and settings in ALLCAPS being the default.
+
 .. versionadded:: 2.0
    *Before* version 2.0, boolean (i.e. "``true|false``") or "flag"
    parameters, register as true, if they appear in the configuration
@@ -50,6 +54,8 @@ Settings
    Increases the amount of internal reporting returned on standard
    output or in the log file generated by :setting:`logpath`.
 
+TODO: I would figure out a way to collapse these, and try to explain the levels of verbosity. I cannot enumerate them yet.
+
    .. setting:: v
 
       *Default:* false
@@ -82,6 +88,8 @@ Settings
 
 .. setting:: quiet
 
+TODO: Since we've declared above that configs can be used for mongod and mongos, either state that the config item applies to both, or don't state that at all.
+
    *Default:* false
 
    Runs the :program:`mongod` instance in a quiet mode that attempts to limit
@@ -99,6 +107,8 @@ Settings
 
    *Default:* 127.0.0.1
 
+TODO: I think this is not true. I think we default to *, and SHOULD default to 127.0.0.1
+
    Set this option to configure the :program:`mongod` process to bind
    to and listen for connections from applications on this
    address. You may attach :program:`mongod` to any interface;
@@ -112,6 +122,7 @@ Settings
 .. setting:: maxConns
 
    *Default:* depends on system settings.
+   TODO: Enumerate what system setting this is dependent on.
 
    Specifies a value to set the maximum number of simultaneous
    connections that :program:`mongod` or :program:`mongos` will
@@ -131,6 +142,9 @@ Settings
 
    *Default:* false
 
+TODO: Since this option tells me that invalid BSON data would never get inserted to the DB, we should explain why the default is false.
+I believe it has to do with overhead, and we should explain what that is. 
+
    Set to ``true`` to force :program:`mongod` to validate all requests
    from clients upon receipt to ensure that invalid objects are never
    inserted into the database.
@@ -139,19 +153,25 @@ Settings
 
    *Default:* None. (i.e. ``/dev/stdout``)
 
+TODO: Explain that this setting to to a filename, _not_ a directory.
+
    Specify a path for the log file that will hold all diagnostic
    logging information.
 
    Unless specified, :program:`mongod` will output all log information
    to the standard output. Unless :setting:`logappend` is ``true``,
    the logfile will be overwritten when the process restarts.
 
+TODO: Follow this ticket for behavioral change on this topic: https://jira.mongodb.org/browse/SERVER-4499
+
 .. setting:: logappend
 
    *Default:* false
 
    Set to ``true`` to add new entries to the end of the logfile rather
    than overwriting the content of the log when the process restarts.
+   
+TODO: same as above
 
 .. setting:: syslog
 
@@ -205,6 +225,8 @@ Settings
 
    Set to ``true`` to enable a :term:`daemon` mode for :program:`mongod`
    which forces the process to the background.
+   
+   TODO: "forces" vs "forks"?
 
 .. setting:: auth
 
@@ -232,11 +254,13 @@ Settings
 
    Set this value to designate a directory for the :program:`mongod`
    instance to store its data. Typical locations include:
-   "``/srv/mognodb``", "``/var/lib/mongodb``" or "``/opt/mongodb``"
+   "``/srv/mongodb``", "``/var/lib/mongodb``" or "``/opt/mongodb``"
 
    Unless specified, :program:`mongod` creates data files in the
    default ``/data/db`` directory. (Windows systems use the
    ``\data\db`` directory.)
+   
+   TODO: Inaccurate. While we expect this dir by default, if it does not exist on first run, mongod will error out and exit. Also, packages have distinct locations for db storage that are created upon install and the conf for those has it applied.
 
 .. setting:: diaglog
 
@@ -246,6 +270,8 @@ Settings
    :program:`mongod` instance. Possible values, and their impact are
    as follows.
 
+TODO: Explain which diaglog this is, since we call the "logpath" for diagnostic logging, and this logging may be in another log file. 
+
    =========  ===================================
    **Value**  **Setting**
    ---------  -----------------------------------
@@ -264,10 +290,15 @@ Settings
    to store each database's files in a distinct folder. Use this option to
    configure MongoDB to store data on a number of distinct disk
    devices to increase write throughput or disk capacity.
+   
+TODO: Explain the distinct folder naming scheme
 
    Unless specified, :program:`mongod` saves all database files in the
    directory specified by :setting:`dbpath`.
 
+TODO: Since all files will be in dpath anyways, and just branch off the root of that dir, maybe this statement should be explained better.
+
+
 .. setting:: journal
 
    *Default:* (on 64-bit systems) true
@@ -316,11 +347,15 @@ Settings
 
    For consistency use the :setting:`auth` option.
 
+TODO: I didn't see a refernce here for the auth setting - is it missing? Should we have both auth and noauth?
+
 .. setting:: nohttpinterface
 
    *Default:* false
 
    Set to ``true`` to disable the HTTP interface.
+   
+TODO: Does disabling with nohttp override jsonp and rest commands? Do they reenable http? Don't know.
 
 .. setting:: nojournal
 
@@ -332,6 +367,8 @@ Settings
    default, :program:`mongod` enables journaling in 64-bit versions
    after v2.0.
 
+TODO: Same as auth/noauth - what do we do with journal/nojournal?
+
 .. setting:: noprealloc
 
    *Default:* false
@@ -360,7 +397,7 @@ Settings
    Specify this value in megabytes.
 
    Use this setting to control the default size for all newly created
-   namespace files (i.e ``.NS``). This option has no impact on the
+   namespace files (i.e ``.ns``). This option has no impact on the
    size of existing namespace files.
 
    The default value is 16 megabytes, this provides for effectively
@@ -374,6 +411,8 @@ Settings
    inserts information about operation performance into output of
    :program:`mongod` or the log file. The following levels are
    available:
+   
+TODO: "or the log file" - maybe explain why it would go to the logfile? If `logpath is specified`?
 
    =========  ==================================
    **Level**  **Setting**
@@ -383,7 +422,7 @@ Settings
       2       On. Includes all operations.
    =========  ==================================
 
-   By default, :program:`mongod` disables profiling Database profiling
+   By default, :program:`mongod` disables profiling. Database profiling
    can impact database performance because the profiler must record
    and process all database operations. Enable this option only after
    careful consideration.
@@ -459,12 +498,14 @@ Settings
    file size for data files and limits the maximum file size to 512
    megabytes. Use :setting:`smallfiles` if you have a large number of
    databases that each holds a small quaint of data.
+   
+TODO: I think "quaint" in the last line is quaint, but probably meant amount or something else.
 
 .. setting:: syncdelay
 
    *Default:* 60
 
-   This setting contrils the maximum number of seconds between disk
+   This setting controls the maximum number of seconds between disk
    syncs. While :program:`mongod` is always writing data to disk, this
    setting controls the maximum guaranteed interval between a
    successful write operation and the next time the database flushes
@@ -489,6 +530,15 @@ Settings
 
    More typically, run this operation by way of the :option:`mongod
    --sysinfo` command.
+   
+TODO: What kind of system info is returned? Is it helpful, used in any way?
+Here's an output from a production server:
+Tue Mar  6 13:48:57 sysinfo:
+Tue Mar  6 13:48:57   page size: 4096
+Tue Mar  6 13:48:57   _SC_PHYS_PAGES: 4116145
+Tue Mar  6 13:48:57   _SC_AVPHYS_PAGES: 30950
+
+I don't know what these values mean, nor what units they are measured in.
 
 .. setting:: upgrade
 
@@ -503,6 +553,8 @@ Settings
 
    When specified for a :program:`mongos` instance, this option updates
    the meta data format used by the :term:`config database`.
+   
+TODO: Is this still a thing? When/where do we tell someone to run this command?
 
 Replica Set Options
 ```````````````````
@@ -523,6 +575,11 @@ Replica Set Options
       secondary or slave will be permanently out of sync with the
       primary, which may cause significant consistency problems.
 
+TODO: Since we recommend a resync as a recommended method of bringing up a new member of a replica set, is this part of replsets, or master/slave?
+I found this:
+--fastsync	 If the node has a completely up-to-date copy of the data, use this option to let it know it can skip the resync. Be careful – the server will assume it is caught up completely and if not so the data will be out of sync permanently.
+here: http://www.mongodb.org/display/DOCS/Command+Line+Parameters
+
 .. setting:: oplogSize
 
 o   Specifies a maximum size in megabytes for the replication operation
@@ -563,6 +620,8 @@ Master/Slave Replication
 
    Used with the :setting:`slave` option, the ``only`` setting
    specifies only a single :term:`database` to replicate.
+   
+TODO: I don't think this is a true/false, rather a db name
 
 .. setting:: slavedelay
 
@@ -591,6 +650,8 @@ Master/Slave Replication
 Replica Set Options
 ```````````````````
 
+TODO: Is it me, or are there two replica set options sections?
+
 .. setting:: replSet
 
    *Default:* <none>
@@ -602,13 +663,15 @@ Replica Set Options
    Use this setting to configure replication with replica
    sets. Specify a replica set name as an argument to this set. All
    hosts must have the same set name. You can add one or more "seed"
-   hosts to one or more host in the set to initiate the cluster. Use
+   hosts to one or more hosts in the set to initiate the cluster. Use
    the following form: ::
 
         replSet = <setname>/<host1>,<host2>:<port>
 
    When you add or reconfigure the replica set on one host, these
    changes propagate throughout the cluster.
+   
+TODO: Do they? If they are set in a config file, then probably not. Maybe "When you add or reconfig.. should be propagated"?
 
 Sharding Cluster Options
 ````````````````````````
@@ -648,6 +711,8 @@ Sharding Cluster Options
    (i.e. :term:`config database`) for the :term:`shard cluster`. You may
    specify either 1 configuration server or 3 configuration servers,
    in a comma separated list.
+   
+TODO: May vs must?
 
    This setting only affects :program:`mongos` processes.
 

source/reference/mongod.rst

@@ -163,7 +163,7 @@ Options
 .. option:: --cpu
 
    Forces :program:`mongod` to report the percentage of CPU time in
-   write lock. :program:`mongod` generates output ever four
+   write lock. :program:`mongod` generates output every four
    seconds. MongoDB writes this data to standard output or the logfile
    if using the :setting:`logpath` option.