Skip to content

Commit f6b2b0d

Browse files
committed
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.
1 parent 35260bb commit f6b2b0d

File tree

2 files changed

+80
-54
lines changed

2 files changed

+80
-54
lines changed

docs/introduction/overview.rst

+50-27
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
The Nature of Kotti
22
===================
33

4-
Kotti is a software framework used to build websites and web applications.
4+
Kotti is a software system used to build websites and web applications.
55

66
As a user, you don't have to know about the languages used, nor about the focus
77
on browser or server programming described below. You just use a website made
88
with Kotti. However, understanding the nature of the software will stimulate
9-
an appreciation of its strengths and confidence in using it. Also, knowledge of
10-
the general environment of website and web applications can help to demysify
11-
new ways we all use software, from traditional desktop apps, to the many "apps"
12-
available for the iPhone, Android, and mobile devices, to the web-oriented
13-
systems like those built with Kotti.
9+
an appreciation of its strengths and build confidence in using it. Knowledge of
10+
the general environment of website and web application software can help you
11+
understand new ways we use software today, as compared to traditional desktop
12+
apps, and the many "apps" available for the iPhone, Android, and mobile
13+
devices.
1414

1515
Websites and web apps come in so many varieties. Broadly, for the modern World
1616
Wide Web, several main development approaches are used:
@@ -40,13 +40,31 @@ Wide Web, several main development approaches are used:
4040
Kotti uses the second approach primarily, in its default configuration, but has
4141
the flavor of a combined approach, with the latest browser programming
4242
techniques used for parts of the user interface, and with the programming
43-
language Python forming the heart of the system on the server. Kotti uses an
44-
expressive programming interface to the database called SQLAlchemy, providing
45-
the "secret sauce" for working intelligently with data.
43+
language ``Python`` forming the heart of the system on the server. Kotti uses
44+
an expressive programming system called ``Pyramid`` that forms a very good
45+
foundation. Kotti uses an interface to data called ``SQLAlchemy``, that
46+
provides an intelligent way to work with a choice of solid databases.
4647

4748
Kotti forms a great platform for extending with browser programming of advanced
48-
graphics and presentation features, to allow a powerful combination of the
49-
approaches described above.
49+
graphics and presentation features, combining the approaches described above in
50+
the construction of web applications that go beyond the traditional CMS.
51+
52+
Your Kotti-based website could be an out-of-the-box default site with just a
53+
few add-ons, or it could be a heavily customized site or web app. This user
54+
manual covers use of a default configuration, but should be useful for learning
55+
about any Kotti-based system.
56+
57+
.. Note:: What's the difference between a website and a web app? A website
58+
often appears as multiple pages, and may stress the presentation of
59+
static information, while including traditional web forms for
60+
accepting input from users. A web app in classic form will appear as
61+
a single page with displays that swap out for one another in place,
62+
working more like a desktop application on your computer. These
63+
distinctions need not be limiting; a Kotti system can be built that
64+
has multiple pages, some of which can constitute "web apps" on their
65+
own. One page might present text and images for a static document.
66+
Another might involve dynamic graphics, "rich" interactivity, and
67+
multiple screens that swap out.
5068

5169
Design Goals
5270
============
@@ -56,7 +74,8 @@ formed by a group of dedicated software developers has assembled. Many of the
5674
developers have years of experience in CMS projects and in the languages used
5775
in Kotti. The future looks bright for the adoption of Kotti for small and large
5876
websites, for internal company systems, for social media, and many other
59-
niches. It is a capable CMS with high potential.
77+
niches. It is a capable CMS on its own, and forms a solid base for programming
78+
in the modern world of the web.
6079

6180
Programmers of Kotti try to:
6281

@@ -66,22 +85,26 @@ Programmers of Kotti try to:
6685
* work collaboratively, using modern development tools, and
6786
* test the software continuously.
6887

69-
The design of Kotti has content storage as something like an outline or tree,
70-
where content is nested in a meaningful way. This is the *natural* design
71-
aspect. The Document content type is the most important part of this concept.
88+
The design of Kotti features content storage as something like an outline or
89+
tree, where content is nested in a meaningful way. This is the *natural*
90+
design aspect, for which the Document content type is central.
91+
7292
Documents are added to a Kotti website in the way word-processor documents are
7393
created on computers, but in the context of the web. Documents contain text and
7494
may include images, files, and links to other documents. Kotti's design makes
7595
linking documents to one another happen automatically as the site structure is
76-
built. There are easy ways to make custom links between content items, or to
77-
other websites.
78-
79-
Reiterating the centrol role for the Document content type in organization, we
80-
can describe a typical usage scenario. You add documents for each main part of
81-
your website. You add documents within those. If your site has a deep
82-
structure, you add documents within documents within documents to form a deep
83-
nested structure. Everything else can be considered secondary for importance
84-
in organization, because you store images, files, and custom content items
85-
within documents as the structure unfolds during site construction. A given
86-
document will have its own textual content, and will serve as the storage
87-
location for the associated images and files displayed or linked there.
96+
built, document by document. There are easy ways to make custom links from
97+
documents to other content items, or to other websites.
98+
99+
.. Note:: A document, thus, does double-duty, presenting its own textual and
100+
graphical content, while serving as the storage location for the
101+
associated images and files displayed or linked therein. A document
102+
is linked to its parent document, and may contain any number of child
103+
documents.
104+
105+
Consider a typical usage scenario for a fresh Kotti CMS website: You first add
106+
documents for each main part of your website. You then add documents within
107+
those. You may add documents within documents within documents to form a deeply
108+
nested structure. Other content types can be considered secondary for
109+
importance in organization, because you store images, files, and custom content
110+
items within documents as the structure unfolds during site construction.

docs/introduction/users_and_roles.rst

+30-27
Original file line numberDiff line numberDiff line change
@@ -20,34 +20,37 @@ In its simplest form, Kotti allows a special user, called the Admin user, to
2020
log in and add and edit content. The Admin user has full rights to do anything
2121
to the website.
2222

23-
.. Note:: If you are just such a person, the sole user for a Kotti website, you
24-
may wish to skip the rest of this section, and that of the next, and
25-
go directly to the section presenting an
26-
:ref:`fresh-kotti-site-example`. The discussion below about user
27-
roles and workflow is important for larger websites with multiple
28-
users and more complex content organization.
23+
In Kotti websites with just one user, the site administrator may simply tell
24+
this sole user to use the Admin account, or they might set up an account for
25+
the user, and give this user account full content-adding and editing rights to
26+
the site, equivalent to the Admin user. Either way, there is just one user
27+
adding content, and this is inherently simpler than a multi-user system.
2928

30-
For a larger Kotti website, where several people add content, the Admin user
31-
may create accounts for other people. One common approach is to divide the
32-
website into several top-level sections that different people manage. For
33-
example, imagine a scenario where Joe, Sally, and Xavier are the content
34-
managers for a musical act agency. First the Admin user logs in (perhaps the
35-
Admin user is one of Joe, Sally, or Xavier; perhaps it is a fourth person),
36-
creates the three accounts for Joe, Sally, and Xavier, then sends them emails
37-
with user names and passwords. The Admin user also creates three top-level
38-
sections of the website, notifying Joe, Sally, and Xavier about their
39-
responsibilities: Joe for the ``Prospects`` section, Sally for the ``Existing
40-
Clients`` section, and Xavier for the ``Legal Affairs`` section. The Admin
41-
user assigns rights to these three areas by creating three user groups:
42-
prospects, existing_clients, and legal_affairs. Then, by setting the
43-
respective groups as owners of the three website sections, a scheme for
44-
organization and responsibility is established. Additional people can be added
45-
by simply assigning them to a given group. For example, if Judy works with
46-
Xavier on the legal team, the Admin user creates a new account for Judy, then
47-
assigns her to the legal_affairs group, then emails her about the new account
48-
and her responsibilities. Judy and Xavier will both have rights to add and
49-
edit content in the ``Legal Affairs`` section. Joe, Sally, Xavier, and Judy
50-
share responsibilities like this:
29+
If you are such a sole user for a Kotti website, you may wish to skip the rest
30+
of this section, and the next, and go directly to the section presenting
31+
:ref:`fresh-kotti-site-example`. The discussion below and in the next section,
32+
about user roles and workflow, is important for websites where multiple users
33+
add content and where there is a more complex content organization.
34+
35+
For a Kotti website, where several people add content, the Admin user may
36+
create accounts for other people. One common approach is to divide the website
37+
into several top-level sections that different people manage. For example,
38+
imagine a scenario where Joe, Sally, and Xavier are the content managers for a
39+
musical act agency. First the Admin user logs in, then creates the three
40+
accounts for Joe, Sally, and Xavier, then sends them emails with user names and
41+
passwords. The Admin user also creates three top-level sections of the website,
42+
and notifies Joe, Sally, and Xavier about their responsibilities: Joe for the
43+
``Prospects`` section, Sally for the ``Existing Clients`` section, and Xavier
44+
for the ``Legal Affairs`` section. The Admin user assigns rights to these
45+
three areas by creating three user groups: prospects, existing_clients, and
46+
legal_affairs. Then, by setting the respective groups as owners of the three
47+
website sections, a scheme for organization and responsibility is established.
48+
Additional people can be added by simply assigning them to a given group. For
49+
example, if Judy works with Xavier on the legal team, the Admin user creates a
50+
new account for Judy, then assigns her to the legal_affairs group, then emails
51+
her about the new account and her responsibilities. Judy and Xavier will both
52+
have rights to add and edit content in the ``Legal Affairs`` section. Joe,
53+
Sally, Xavier, and Judy share responsibilities like this:
5154

5255
.. Image:: ../images/roles_music_agency.png
5356

0 commit comments

Comments
 (0)