"About the Documentation" (primarily: prerequisites)

[Joshua Slive <jo...@slive.ca>]

Here is an idea for a document to go in the release notes section of the
manual.

What do you think?  Is it asking to much to insist people know what an
"HTTP status code" is before they read the docs?  What would be a better
example?


<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
<manualpage metafile="about.xml.meta">

<title>About the Documentation</title>

<summary>
  <p>This document describes the basic purpose of this manual,
  the assumptions behind it, and provides some links to useful
  supplementary material.</p>
</summary>

<section id="assumptions">
<title>Assumptions</title>

<p>It is impossible for one set of documentation to satisfy every type
of user. As documentation authors, we do our best to achieve the
appropriate balance between the needs of advanced and novice users.
But we do assume that our readers have an adequate background in order
to understand the material.</p>

<p>In particular, we assume that readers of this manual:</p>

<ul>

<li>Are familiar with administering their chosen operating system.
This includes manipulation of files and processes, as well as network
configuration.</li>

<li>Have a basic understanding of the technologies of the web, and
HTTP in particular.  This includes, for example, understanding what is
an HTTP status code and an HTTP response header.</li>

</ul>
</section>

<section id="novice">
<title>Tips for Novice Users</title>

<p>What if you don't have the prerequisite knowledge?  All is not lost.
Here are some suggestions on how to get up-to-speed.</p>

<ul>

<li>The manual includes a <a href="glossary.html">glossary</a> that
defines
many of the terms we use.</li>

<li>The <a href="howto/">tutorials</a> section of the manual
contains some introductory-level guides to certain Apache features.</li>

<li>Many good <a
href="http://httpd.apache.org/info/apache_books.html">books</a> are
available documenting the Apache HTTP Server.  Most of these books
provide more background information, and are therefore better suited
to novice users than the official documentation.</li>

<li>We provide a <a href="http://httpd.apache.org/library/">project
library</a> with background information on many of the technologies
used in Apache.</li>

<li>The <a href="faq/">FAQ</a> provides links to user-support forums
where you can get guidance from more experienced users.</li>

</ul>

</section>

<section id="format">
<title>Documentation Format</title>

<p>The documentation is available in several different formats.  For
more information, see the <a
href="http://httpd.apache.org/docs-project/">Documentation Project</a>
page.</p>

</section>

</manualpage>


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: "About the Documentation" (primarily: prerequisites)

[Astrid Keßler <ke...@kess-net.de>]

> Here is an idea for a document to go in the release notes section of the
> manual.

+1

> What do you think?  Is it asking to much to insist people know what an
> "HTTP status code" is before they read the docs?  What would be a better
> example?

Some first time users may use HTTP header or status code as a black box
and won't know much more then staus 404. I remember my first steps. I
set up a server at my local machine to test cgi's not knowing how the
server works. At this level I did not need and want more documentation
then how to install the server and make it serving cgis.

To be able to _work_ with apache and its doc, know-how about basic
concepts are nesseccary. I think, the level is ok.

But it would be fine to have a direct link to a document explaining the
HTTP basics in a beginners friendly way.

Kess

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org