Changed a note containing a section link to plain paragraph; the link must have caused a problem as the note was skipped. Reworked the overview again, with more contrast between website and web app, and better description of Document. Pyramid and SQLAlchemy are presented in name now, in the design section.

Author: geojeff

docs/introduction/overview.rst

@@ -1,16 +1,16 @@
 The Nature of Kotti
 ===================
 
-Kotti is a software framework used to build websites and web applications. 
+Kotti is a software system used to build websites and web applications. 
 
 As a user, you don't have to know about the languages used, nor about the focus
 on browser or server programming described below. You just use a website made
 with Kotti.  However, understanding the nature of the software will stimulate
-an appreciation of its strengths and confidence in using it. Also, knowledge of
-the general environment of website and web applications can help to demysify
-new ways we all use software, from traditional desktop apps, to the many "apps"
-available for the iPhone, Android, and mobile devices, to the web-oriented
-systems like those built with Kotti.
+an appreciation of its strengths and build confidence in using it. Knowledge of
+the general environment of website and web application software can help you
+understand new ways we use software today, as compared to traditional desktop
+apps, and the many "apps" available for the iPhone, Android, and mobile
+devices.
 
 Websites and web apps come in so many varieties. Broadly, for the modern World
 Wide Web, several main development approaches are used:
@@ -40,13 +40,31 @@ Wide Web, several main development approaches are used:
 Kotti uses the second approach primarily, in its default configuration, but has
 the flavor of a combined approach, with the latest browser programming
 techniques used for parts of the user interface, and with the programming
-language Python forming the heart of the system on the server.  Kotti uses an
-expressive programming interface to the database called SQLAlchemy, providing
-the "secret sauce" for working intelligently with data.
+language ``Python`` forming the heart of the system on the server.  Kotti uses
+an expressive programming system called ``Pyramid`` that forms a very good
+foundation.  Kotti uses an interface to data called ``SQLAlchemy``, that
+provides an intelligent way to work with a choice of solid databases.
 
 Kotti forms a great platform for extending with browser programming of advanced
-graphics and presentation features, to allow a powerful combination of the
-approaches described above.
+graphics and presentation features, combining the approaches described above in
+the construction of web applications that go beyond the traditional CMS.
+
+Your Kotti-based website could be an out-of-the-box default site with just a
+few add-ons, or it could be a heavily customized site or web app. This user
+manual covers use of a default configuration, but should be useful for learning
+about any Kotti-based system.
+
+.. Note:: What's the difference between a website and a web app? A website
+          often appears as multiple pages, and may stress the presentation of
+          static information, while including traditional web forms for
+          accepting input from users. A web app in classic form will appear as
+          a single page with displays that swap out for one another in place,
+          working more like a desktop application on your computer.  These
+          distinctions need not be limiting; a Kotti system can be built that
+          has multiple pages, some of which can constitute "web apps" on their
+          own. One page might present text and images for a static document.
+          Another might involve dynamic graphics, "rich" interactivity, and
+          multiple screens that swap out.
 
 Design Goals
 ============
@@ -56,7 +74,8 @@ formed by a group of dedicated software developers has assembled. Many of the
 developers have years of experience in CMS projects and in the languages used
 in Kotti. The future looks bright for the adoption of Kotti for small and large
 websites, for internal company systems, for social media, and many other
-niches. It is a capable CMS with high potential.
+niches. It is a capable CMS on its own, and forms a solid base for programming
+in the modern world of the web.
 
 Programmers of Kotti try to:
 
@@ -66,22 +85,26 @@ Programmers of Kotti try to:
 * work collaboratively, using modern development tools, and
 * test the software continuously.
 
-The design of Kotti has content storage as something like an outline or tree,
-where content is nested in a meaningful way.  This is the *natural* design
-aspect.  The Document content type is the most important part of this concept.
+The design of Kotti features content storage as something like an outline or
+tree, where content is nested in a meaningful way.  This is the *natural*
+design aspect, for which the Document content type is central.
+
 Documents are added to a Kotti website in the way word-processor documents are
 created on computers, but in the context of the web. Documents contain text and
 may include images, files, and links to other documents.  Kotti's design makes
 linking documents to one another happen automatically as the site structure is
-built.  There are easy ways to make custom links between content items, or to
-other websites. 
-
-Reiterating the centrol role for the Document content type in organization, we
-can describe a typical usage scenario. You add documents for each main part of
-your website.  You add documents within those. If your site has a deep
-structure, you add documents within documents within documents to form a deep
-nested structure.  Everything else can be considered secondary for importance
-in organization, because you store images, files, and custom content items
-within documents as the structure unfolds during site construction. A given
-document will have its own textual content, and will serve as the storage
-location for the associated images and files displayed or linked there.
+built, document by document.  There are easy ways to make custom links from
+documents to other content items, or to other websites. 
+
+.. Note:: A document, thus, does double-duty, presenting its own textual and
+          graphical content, while serving as the storage location for the
+          associated images and files displayed or linked therein. A document
+          is linked to its parent document, and may contain any number of child
+          documents.
+
+Consider a typical usage scenario for a fresh Kotti CMS website: You first add
+documents for each main part of your website.  You then add documents within
+those. You may add documents within documents within documents to form a deeply
+nested structure.  Other content types can be considered secondary for
+importance in organization, because you store images, files, and custom content
+items within documents as the structure unfolds during site construction.

docs/introduction/users_and_roles.rst

@@ -20,34 +20,37 @@ In its simplest form, Kotti allows a special user, called the Admin user, to
 log in and add and edit content. The Admin user has full rights to do anything
 to the website.
 
-.. Note:: If you are just such a person, the sole user for a Kotti website, you
-          may wish to skip the rest of this section, and that of the next, and
-          go directly to the section presenting an
-          :ref:`fresh-kotti-site-example`. The discussion below about user
-          roles and workflow is important for larger websites with multiple
-          users and more complex content organization.
+In Kotti websites with just one user, the site administrator may simply tell
+this sole user to use the Admin account, or they might set up an account for
+the user, and give this user account full content-adding and editing rights to
+the site, equivalent to the Admin user. Either way, there is just one user
+adding content, and this is inherently simpler than a multi-user system.
 
-For a larger Kotti website, where several people add content, the Admin user
-may create accounts for other people. One common approach is to divide the
-website into several top-level sections that different people manage. For
-example, imagine a scenario where Joe, Sally, and Xavier are the content
-managers for a musical act agency. First the Admin user logs in (perhaps the
-Admin user is one of Joe, Sally, or Xavier; perhaps it is a fourth person),
-creates the three accounts for Joe, Sally, and Xavier, then sends them emails
-with user names and passwords. The Admin user also creates three top-level
-sections of the website, notifying Joe, Sally, and Xavier about their
-responsibilities: Joe for the ``Prospects`` section, Sally for the ``Existing
-Clients`` section, and Xavier for the ``Legal Affairs`` section.  The Admin
-user assigns rights to these three areas by creating three user groups:
-prospects, existing_clients, and legal_affairs.  Then, by setting the
-respective groups as owners of the three website sections, a scheme for
-organization and responsibility is established.  Additional people can be added
-by simply assigning them to a given group. For example, if Judy works with
-Xavier on the legal team, the Admin user creates a new account for Judy, then
-assigns her to the legal_affairs group, then emails her about the new account
-and her responsibilities.  Judy and Xavier will both have rights to add and
-edit content in the ``Legal Affairs`` section. Joe, Sally, Xavier, and Judy
-share responsibilities like this:
+If you are such a sole user for a Kotti website, you may wish to skip the rest
+of this section, and the next, and go directly to the section presenting
+:ref:`fresh-kotti-site-example`. The discussion below and in the next section,
+about user roles and workflow, is important for websites where multiple users
+add content and where there is a more complex content organization.
+
+For a Kotti website, where several people add content, the Admin user may
+create accounts for other people. One common approach is to divide the website
+into several top-level sections that different people manage. For example,
+imagine a scenario where Joe, Sally, and Xavier are the content managers for a
+musical act agency. First the Admin user logs in, then creates the three
+accounts for Joe, Sally, and Xavier, then sends them emails with user names and
+passwords. The Admin user also creates three top-level sections of the website,
+and notifies Joe, Sally, and Xavier about their responsibilities: Joe for the
+``Prospects`` section, Sally for the ``Existing Clients`` section, and Xavier
+for the ``Legal Affairs`` section.  The Admin user assigns rights to these
+three areas by creating three user groups: prospects, existing_clients, and
+legal_affairs.  Then, by setting the respective groups as owners of the three
+website sections, a scheme for organization and responsibility is established.
+Additional people can be added by simply assigning them to a given group. For
+example, if Judy works with Xavier on the legal team, the Admin user creates a
+new account for Judy, then assigns her to the legal_affairs group, then emails
+her about the new account and her responsibilities.  Judy and Xavier will both
+have rights to add and edit content in the ``Legal Affairs`` section. Joe,
+Sally, Xavier, and Judy share responsibilities like this:
 
 .. Image:: ../images/roles_music_agency.png