adds a table of content, some minor layout and text changes

1 files changed, 83 insertions, 113 deletions

diff --git a/english/doc/index.wml b/english/doc/index.wml
index 6fd5b1ce48c..43b7b3bd2dd 100644
--- a/english/doc/index.wml
+++ b/english/doc/index.wml
@@ -1,59 +1,67 @@
-#use wml::debian::template title="Documentation"
+#use wml::debian::template title="Documentation" MAINPAGE="true"
+#use wml::debian::recent_list
 
-<p>An important part of any operating system is documentation, the technical
-manuals that describe the operation and use of programs. As part of its efforts
-to create a high-quality free operating system, the Debian Project is making
-every effort to provide all of its users with proper documentation in an
-easily accessible form.</p>
+<link href="$(HOME)/font-awesome.css" rel="stylesheet" type="text/css">
 
-<h2>Quick start</h2>
+<ul class="toc">
+  <li><a href="#quick_start">Quick Start</li>
+  <li><a href="#manuals">Manuals</li>
+  <li><a href="#other">Other (shorter) Documents</a></li>
+</ul>
+
+<p>
+Creating a high-quality free operating system also includes writing technical manuals which describe the operation and use of programs. The Debian project is making every effort to provide all users with good documentation in an easily accessible form. This page contains a collection of links, leading to installation guides, HOWTOs, FAQs, release notes, our Wiki, and more.
+</p>
+
+
+<h2><a id="quick_start">Quick Start</a></h2>
 
-<p>If you are <em>new</em> to Debian we recommend you start first by
-reading:</p>
+<p>
+If you are new to Debian we recommend you start with the following two guides:
+</p>
+
+<aside class="light">
+  <span class="fas fa-fast-forward fa-5x"></span>
+</aside>
 
 <ul>
   <li><a href="$(HOME)/releases/stable/installmanual">Installation Guide</a></li>
   <li><a href="manuals/debian-faq/">Debian GNU/Linux FAQ</a></li>
 </ul>
 
-<p>Do have these at hand when you make your first Debian installation, it
+<p>
+Do have these at hand when you make your first Debian installation, it
 will probably answer many questions and help you work with your new Debian
-system. Later you might want to go through:</p>
+system. 
+</p>
 
-<ul>
-  <li><a href="manuals/debian-handbook/">The Debian Administrator's Handbook</a>, the comprehensive user manual</li>
-  <li><a href="manuals/debian-reference/">Debian Reference</a>,
-      a terse user's guide with the focus on the shell command line</li>
-  <li><a href="$(HOME)/releases/stable/releasenotes">Release Notes</a>,
-      for people who are upgrading</li>
-  <li><a href="https://wiki.debian.org/">Debian Wiki</a>, a good source
-      of information for newcomers</li>
-</ul>
+<p>
+Later, you might want to go through these documents:
+</p>
 
+  <li><a href="manuals/debian-reference/">Debian Reference</a>: a terse user guide, focussing on shell commands</li>
+  <li><a href="$(HOME)/releases/stable/releasenotes">Release Notes</a>: usually published with Debian updates, aiming at users upgrading the distribution</li>
+  <li><a href="https://wiki.debian.org/">Debian Wiki</a>: official Debian wiki and a good source of information for newcomers</li>
+</ul>
 
-<p>Finally, make sure you print out and have at hand the <a
-href="https://www.debian.org/doc/manuals/refcard/refcard">Debian GNU/Linux Reference
-Card</a>, a listing of the most important commands for Debian systems.</p>
-
-<p>There is a fair bit of other documentation listed below.</p>
+<p style="text-align:center"><button type="button"><span class="fas fa-print fa-2x"></span> <a href="https://www.debian.org/doc/manuals/refcard/refcard">Print the Debian GNU/Linux Reference Card</a></button></p>
 
-<h2>Types of documentation</h2>
+<h2><a id="manuals">Manuals</a></h2>
 
-<p>Most of the documentation included in Debian was written for GNU/Linux
-in general. There is also some documentation written specifically for Debian.
-These documents come in these basic categories:</p>
+<p>
+Most of the documentation included in Debian was written for GNU/Linux in general, but there is also some documentation written specifically for Debian. Basically, the documents are sorted into these categories:
+</p>
 
 <ul>
-  <li><a href="#manuals">manuals</a></li>
-  <li><a href="#howtos">HOWTOs</a></li>
-  <li><a href="#faqs">FAQs</a></li>
-  <li><a href="#other">other shorter documents</a></li>
+  <li>Manuals: Those guides resemble books, because they comprehensively describe major topics. A lot of manuals listed below are available both online and in Debian packages. In fact, most of the manuals on the website are extracted from their respective Debian packages. Choose a manual below for its package name and/or links to the online versions.</li>
+  <li>HOWTOs: Like the name indicates, the <a href="https://www.tldp.org/HOWTO/HOWTO-INDEX/categories.html">HOWTO documents</a> describe <em>how to</em> do a particular thing, i.e. they offer detailed and practical advice about the way to do something.</li>
+  <li>FAQs: We have compiled several documents answering <em>frequently asked questions</em>. Debian-related questions are answered in the <a href="manuals/debian-faq/">Debian FAQ</a>. Additionally, there is a separate <a href="../CD/faq/">FAQ about Debian CD/DVD images</a>, answering all sorts of questions about installation media.</li> 
+  <li>Other (shorter) Documents:  Please also check the <a href="#other">list</a> of shorter instructions.</li>
 </ul>
 
-<h3 id="manuals">Manuals</h3>
-
-<p>The manuals resemble books, because they comprehensively describe major
-topics.</p>
+<aside>
+<p><span class="fas fa-caret-right fa-3x"></span> For a complete list of Debian manuals and other documentation, please visit the <a href="ddp">Debian Documentation Project</a> page. Additionally, several user-oriented manuals written for Debian GNU/Linux are available as <a href="books">printed books</a>.</p>
+</aside>
 
 <p>Many of the manuals listed here are available both online and in Debian
 packages; in fact, most of the manuals on the website are extracted from
@@ -65,7 +73,7 @@ name and/or links to the online versions.</p>
 <div class="line">
   <div class="item col50">
     
-    <h4><a href="user-manuals">Users' manuals</a></h4>
+    <h4><a href="user-manuals">Manuals for Users</a></h4>
     <ul>
       <li><a href="user-manuals#faq">Debian GNU/Linux FAQ</a></li>
       <li><a href="user-manuals#install">Debian Installation Guide</a></li>
@@ -85,7 +93,7 @@ name and/or links to the online versions.</p>
 
   <div class="item col50 lastcol">
 
-    <h4><a href="devel-manuals">Developers' manuals</a></h4>
+    <h4><a href="devel-manuals">Manuals for Developers</a></h4>
     <ul>
       <li><a href="devel-manuals#policy">Debian Policy Manual</a></li>
       <li><a href="devel-manuals#devref">Debian Developer's Reference</a></li>
@@ -96,99 +104,61 @@ name and/or links to the online versions.</p>
       <li><a href="devel-manuals#dbconfig-common">Guide for database using package maintainers</a></li>
       <li><a href="devel-manuals#dbapp-policy">Policy for packages using databases</a></li>
     </ul>
-    
-    <h4><a href="misc-manuals">Miscellaneous manuals</a></h4>
-    <ul>
-      <li><a href="misc-manuals#history">Debian Project History</a></li>
-    </ul>
 
   </div>
-
-
 </div>
 
-<p class="clr">The complete list of Debian manuals and other documentation can be found
-at the <a href="ddp">Debian Documentation Project</a> web pages.</p>
-
-<p>There are also several user-oriented manuals written for Debian GNU/Linux,
-available as <a href="books">printed books</a>.</p>
-
-<h3 id="howtos">HOWTOs</h3>
-
-<p>The <a href="https://tldp.org/HOWTO/HOWTO-INDEX/categories.html">HOWTO
-documents</a>, like their name says, describe <em>how to</em> do
-something, and they usually cover a more specific subject.</p>
-
-
-<h3 id="faqs">FAQs</h3>
+<p style="text-align:center"><button type="button"><span class="fas fa-book-open fa-2x"></span> <a href="misc-manuals#history">Read the Debian Project History</a></button></p>
 
-<p>FAQ stands for <em>frequently asked questions</em>. A FAQ is a document
-which answers those questions.</p>
-
-<p>Questions specifically related to Debian are answered in the
-<a href="manuals/debian-faq/">Debian FAQ</a>.
-There is also a separate <a href="../CD/faq/">FAQ about Debian CD/DVD
-images</a>.</p>
-
-
-<h3 id="other">Other, shorter documents</h3>
+<h2><a id="other">Other (shorter) Documents</a></h2>
 
 <p>The following documents include quicker, shorter instructions:</p>
 
+<p>
 <dl>
 
-  <dt><strong><a href="https://tldp.org/docs.html#man">manual pages</a></strong></dt>
-    <dd>Traditionally, all Unix programs are documented with <em>manual
-        pages</em>, reference manuals made available through the <tt>man</tt>
-        command. They usually aren't meant for beginners. You can 
-	search for and read the manual pages available in Debian
-	in <a href="https://manpages.debian.org/cgi-bin/man.cgi">https://manpages.debian.org/</a>.
+<aside>
+<p><span class="fas fa-caret-right fa-3x"></span> If you have checked the above resources and still can't find answers to your questions or solutions to your problems regarding Debian, take a look at our <a href="../support">support page</a>.</p>
+</aside>
+
+  <dt><strong><a href="https://tldp.org/docs.html#man">Manpages</a></strong></dt>
+    <dd>Traditionally, all Unix programs are documented with
+    <em>manpages</em>,
+        reference manuals made available through the <tt>man</tt>
+        command. They usually aren't meant for beginners, but
+        document all features and functions of a command. The complete
+        repository of all manpages available in Debian is online: <a
+        href="https://manpages.debian.org/cgi-bin/man.cgi">https://manpages.debian.org/</a>
     </dd>
 
   <dt><strong><a href="https://www.gnu.org/software/texinfo/manual/texinfo/html_node/index.html">info files</a></strong></dt>
     <dd>Many GNU software is documented through <em>info 
-        files</em> instead of manual pages. These files include detailed
-	information of the program itself, options and example usage
-	and are available through the <tt>info</tt>
+        files</em> instead of manpages. These files include detailed
+	information of the program itself, options and example usage.
+	Info pages are available through the <tt>info</tt>
         command.
     </dd>
 
-  <dt><strong>various README files</strong></dt>
-    <dd>The <em>read me</em> files are also common &mdash; they are simple text
-        files that describe a single item, usually a package. You can find
-        a lot of these in the <tt>/usr/share/doc/</tt> subdirectories on
-        your Debian system. Each software package has a subdirectory
-	under it with its own read me files, and might also include
-	configuration examples. Notice that, for larger programs, documentation
-	is typically provided in a separate package (same name as the
-	original package, but ending in <em>-doc</em>).
+  <dt><strong>README files</strong></dt>
+    <dd>README files are simple text
+        files describing a single item, usually a package. You can find a
+        lot of these files in the <tt>/usr/share/doc/</tt> subdirectories
+        on your Debian system. In addition to the README file, some of
+        those directories include configuration examples. Please note
+        that larger programs' documentation is typically provided in a
+        separate package (same name as the original package, but ending
+        in <em>-doc</em>).
     </dd>
 
-  <dt><strong>quick reference cards</strong></dt>
-    <dd>
-        <p>Quick reference cards are very short summaries of a certain
-        (sub)system. Usually, such a reference card provides the mostly
-        used commands on a single piece of paper. Some notable reference
-        cards and collections include:</p>
-        <dl>
-          <dt><a href="https://www.debian.org/doc/manuals/refcard/refcard">Debian
-              GNU/Linux Reference Card</a></dt>
-	    <dd>This card, that can be printed out in a single paper,
-		provides a list of the most important commands and is
-		a good reference for new users of Debian that want to
-		familiarise with them. At least basic knowledge of computer,
-		files, directories and the command line is required.
-		Novice users might want to read the
-		<a href="user-manuals#quick-reference">Debian Reference</a>
-		first.</dd>
-	</dl>
+  <dt><strong><a href="https://www.debian.org/doc/manuals/refcard/refcard">Debian GNU/Linux Reference Card</a></strong></dt>
+    <dd>Reference cards are very short summaries of a certain (sub)system
+        and usually list the most common commands on a single piece of
+        paper. The Debian GNU/Linux Reference Card provides a list of the
+        most important commands of a Debian system. At least basic knowledge
+        of files, directories, and the command line is required. Novice users
+        might want to read the <a href="user-manuals#quick-reference">Debian
+        Reference</a> first.
     </dd>
 
 </dl>
-
-
-<hrline />
-
-<p>If you have checked the above resources and still can't find answers to
-your questions or solutions to your problems regarding Debian, take a look
-at our <a href="../support">support page</a>.</p>
+</p>