Additional documentation cleanup

docs/additional-features/change-logging.md

@@ -0,0 +1,9 @@
+# Change Logging
+
+Every time an object in NetBox is created, updated, or deleted, a serialized copy of that object is saved to the database, along with meta data including the current time and the user associated with the change. These records form a running changelog both for each individual object as well as NetBox as a whole (Organization > Changelog).
+
+A serialized representation is included for each object in JSON format. This is similar to how objects are conveyed within the REST API, but does not include any nested representations. For instance, the `tenant` field of a site will record only the tenant's ID, not a representation of the tenant.
+
+When a request is made, a random request ID is generated and attached to any change records resulting from the request. For example, editing multiple objects in bulk will create a change record for each object, and each of those objects will be assigned the same request ID. This makes it easy to identify all the change records associated with a particular request.
+
+Change records are exposed in the API via the read-only endpoint `/api/extras/object-changes/`. They may also be exported in CSV format.

docs/additional-features/context-data.md

@@ -1,3 +1,3 @@
 # Contextual Configuration Data
 
-Sometimes it is desirable to associate arbitrary data with a group of devices to aid in their configuration. (For example, you might want to associate a set of syslog servers for all devices at a particular site.) Context data enables the association of arbitrary data (expressed in JSON format) to devices and virtual machines grouped by region, site, role, platform, and/or tenancy. Context data is arranged hierarchically, so that data with a higher weight can be entered to override more general lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object.
+Sometimes it is desirable to associate arbitrary data with a group of devices to aid in their configuration. For example, you might want to associate a set of syslog servers for all devices at a particular site. Context data enables the association of arbitrary data to devices and virtual machines grouped by region, site, role, platform, and/or tenant. Context data is arranged hierarchically, so that data with a higher weight can be entered to override more general lower-weight data. Multiple instances of data are automatically merged by NetBox to present a single dictionary for each object.

docs/additional-features/tags.md

@@ -1,8 +1,8 @@
 # Tags
 
-Tags are free-form text labels which can be applied to a variety of objects within NetBox. Tags are created on-demand. Use commas to separate tags when adding multiple tags to an object, e.g. `Inventoried, Monitored`. Use double quotes around a multi-word tag when adding only one tag, e.g. `"Core Switch"`.
+Tags are free-form text labels which can be applied to a variety of objects within NetBox. Tags are created on-demand as they are assigned to objects. Use commas to separate tags when adding multiple tags to an object 9for example: `Inventoried, Monitored`). Use double quotes around a multi-word tag when adding only one tag, e.g. `"Core Switch"`.
 
-Each tag has a label and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes them easier to work with as URL parameters.
+Each tag has a label and a URL-friendly slug. For example, the slug for a tag named "Dunder Mifflin, Inc." would be `dunder-mifflin-inc`. The slug is generated automatically and makes tags easier to work with as URL parameters.
 
 Objects can be filtered by the tags they have applied. For example, the following API request will retrieve all devices tagged as "monitored":
 

docs/administration/replicating-netbox.md

@@ -32,6 +32,8 @@ If you want to export only the database schema, and not the data itself (e.g. fo
 pg_dump -s netbox > netbox_schema.sql
 ```
 
+---
+
 # Replicating Media
 
 NetBox stored uploaded files (such as image attachments) in its media directory. To fully replicate an instance of NetBox, you'll need to copy both the database and the media files.

docs/core-functionality/ipam.md

@@ -58,7 +58,7 @@ Also like prefixes, each IP address can be assigned a status and a role. Statuse
 * Deprecated
 * DHCP
 
-IP address roles are also hard-coded, and can be used to indicate a special condition of the IP address. Role assignment is optional. Available roles include:
+Each IP address can optionally be assigned a special role. Roles are used to indicate some special attribute of an IP address: for example, it is used as a loopback, or is a virtual IP maintained using VRRP. (Note that this differs in purpose from a _functional_ role, and thus cannot be customized.) Available roles include:
 
 * Loopback
 * Secondary

docs/core-functionality/services.md

@@ -1,5 +1,5 @@
 # Services
 
-A service represents a layer four TCP or UDP service available on a device or virtual machine. Each service includes a name, protocol, and port number; for example, "SSH (TCP/22)" or "DNS (UDP/53)."
+A service represents a layer four TCP or UDP service available on a device or virtual machine. For example, you might want to document that an HTTP service is running on a device. Each service includes a name, protocol, and port number; for example, "SSH (TCP/22)" or "DNS (UDP/53)."
 
 A service may optionally be bound to one or more specific IP addresses belonging to its parent device or VM. (If no IP addresses are bound, the service is assumed to be reachable via any assigned IP address.)

docs/core-functionality/tenancy.md

@@ -13,7 +13,7 @@ A tenant represents a discrete entity for administrative purposes. Typically, te
 * Circuits
 * Virtual machines
 
-If a prefix or IP address is not assigned to a tenant, it will appear to inherit the tenant to which its parent VRF is assigned, if any.
+Tenant assignment is used to signify ownership of an object in NetBox. As such, each object may only be owned by a single tenant. For example, if you have a firewall dedicated to a particular customer, you would assign it to the tenant which represents that customer. However, if the firewall serves multiple customers, it doesn't *belong* to any particular customer, so tenant assignment would not be appropriate.
 
 ### Tenant Groups
 

docs/development/index.md

@@ -1,10 +1,18 @@
-# NetBox Structure
+# NetBox Development
+
+NetBox is maintained as a [GitHub project](https://github.com/digitalocean/netbox) under the Apache 2 license. Users are encouraged to submit GitHub issues for feature requests and bug reports, however we are very selective about pull requests. Please see the `CONTRIBUTING` guide for more direction on contributing to NetBox.
+
+All development of the current NetBox release occurs in the `develop` branch; releases are packaged from the `master` branch. The `master` branch should _always_ represent the current stable release in its entirety, such that installing NetBox by either downloading a packaged release or cloning the `master` branch provides the same code base.
+
+# Project Structure
 
 NetBox components are arranged into functional subsections called _apps_ (a carryover from Django verancular). Each app holds the models, views, and templates relevant to a particular function:
 
 * `circuits`: Communications circuits and providers (not to be confused with power circuits)
 * `dcim`: Datacenter infrastructure management (sites, racks, and devices)
+* `extras`: Additional features not considered part of the core data model
 * `ipam`: IP address management (VRFs, prefixes, IP addresses, and VLANs)
 * `secrets`: Encrypted storage of sensitive data (e.g. login credentials)
 * `tenancy`: Tenants (such as customers) to which NetBox objects may be assigned
+* `utilities`: Resources which are not user-facing (extendable classes, etc.)
 * `virtualization`: Virtual machines and clusters

docs/index.md

@@ -1,3 +1,5 @@
+![NetBox](netbox_logo.png "NetBox logo")
+
 # What is NetBox?
 
 NetBox is an open source web application designed to help manage and document computer networks. Initially conceived by the network engineering team at [DigitalOcean](https://www.digitalocean.com/), NetBox was developed specifically to address the needs of network and infrastructure engineers. It encompasses the following aspects of network management:
@@ -10,7 +12,7 @@ NetBox is an open source web application designed to help manage and document co
 * **Data circuits** - Long-haul communications circuits and providers
 * **Secrets** - Encrypted storage of sensitive credentials
 
-# What NetBox Isn't
+# What NetBox Is Not
 
 While NetBox strives to cover many areas of network management, the scope of its feature set is necessarily limited. This ensures that development focuses on core functionality and that scope creep is reasonably contained. To that end, it might help to provide some examples of functionality that NetBox **does not** provide:
 

mkdocs.yml

@@ -43,6 +43,7 @@ pages:
         - Working with Secrets: 'api/working-with-secrets.md'
         - Examples: 'api/examples.md'
     - Development:
+        - Introduction: 'development/index.md'
         - Utility Views: 'development/utility-views.md'
 
 markdown_extensions: