[gentoo-doc-cvs] cvs commit: l-redesign-1.xml

[Lukasz Damentko]

rane        05/10/07 21:52:20

  Modified:    xml/htdocs/doc/en/articles l-awk1.xml
  Added:       xml/htdocs/doc/en/articles l-redesign-1.xml
  Log:
  new article from #104015

Revision  Changes    Path
1.4       +5 -5      xml/htdocs/doc/en/articles/l-awk1.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-awk1.xml?rev=1.4&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-awk1.xml?rev=1.4&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-awk1.xml.diff?r1=1.3&r2=1.4&cvsroot=gentoo

Index: l-awk1.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-awk1.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- l-awk1.xml	10 Sep 2005 21:20:16 -0000	1.3
+++ l-awk1.xml	7 Oct 2005 21:52:20 -0000	1.4
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-awk1.xml,v 1.3 2005/09/10 21:20:16 rane Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-awk1.xml,v 1.4 2005/10/07 21:52:20 rane Exp $ -->
 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
 
 <guide link="/doc/en/articles/l-awk1.xml">
@@ -115,7 +115,7 @@
 </pre>
 
 <pre caption="$1$3">
-$ <i>awk -F":" '{ print "username: " $1 "\t\tuid:" $3" }' /etc/passwd</i>
+$ <i>awk -F":" '{ print "username: " $1 "\t\tuid:" $3 }' /etc/passwd</i>
 username: halt          uid:7
 username: operator      uid:11
 username: root          uid:0
@@ -426,12 +426,11 @@
     Patrick Hartigan's <uri link="http://sparky.rice.edu/~hartigan/awk.html">awk
     tutorial</uri> is packed with handy awk scripts.
   </li>
-<!-- FIXME 404 - i looked around google for it, no success
   <li>
-    <uri link="http://www.teleport.com/~thompson">Thompson's TAWK Compiler</uri>
+    <uri link="http://www.tasoft.com/tawk.html">Thompson's TAWK Compiler</uri>
     compiles awk scripts into fast binary executables. Versions are available
     for Windows, OS/2, DOS, and UNIX.
-  </li>-->
+  </li>
   <li>
     <uri link="http://www.gnu.org/software/gawk/manual/gawk.html">The GNU Awk
     User's Guide</uri> is available for online reference.
@@ -443,3 +442,4 @@
 </chapter>
 
 </guide>
+



1.1                  xml/htdocs/doc/en/articles/l-redesign-1.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-1.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/articles/l-redesign-1.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: l-redesign-1.xml
===================================================================
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/articles/l-redesign-1.xml,v 1.1 2005/10/07 21:52:20 rane Exp $ -->

<guide link="/doc/en/articles/l-redesign-1.xml">
<title>The gentoo.org redesign, Part 1: A site reborn</title>

<author title="Author">
  <mail link="drobbins@g.o">Daniel Robbins</mail>
</author>

<abstract>
Have you ever woken up one morning and suddenly realized that your cute little
personal development Web site isn't really that great? If so, you're in good
company. In this series, Daniel Robbins shares his experiences as he redesigns
the www.gentoo.org Web site using technologies like XML, XSLT, and Python.
Along the way, you may find some excellent approaches to use for your next Web
site redesign. In this article, Daniel creates a user-centric action plan and
introduces pytext, an embedded Python interpreter.
</abstract>

<!-- The original version of this article was first published on IBM
developerWorks, and is property of Westtech Information Services. This
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux Documentation team -->

<version>1.0</version>
<date>2005-10-07</date>

<chapter>
<title>An unruly horde</title>
<section>
<body>

<note>
The original version of this article was published on IBM developerWorks, and
is property of Westtech Information Services. This document is an updated
version of the original article, and contains various improvements made by the
Gentoo Linux Documentation team.
</note>

<p>
Fellow software developer, may I ask you a question? Why is it that although
many of us are intimately familiar with Web technologies such as HTML, CGI,
Perl, Python, Java technology, and XML, our very own Web sites -- the ones
devoted to our precious development projects -- look like they were thrown
together by an unruly horde of hyperactive 12-year-olds? Why, oh why, is this
so?
</p>

<p>
Could it be because most of the time, we've left our Web site out to rot while
we squander our precious time hacking away on our free software projects? The
answer, at least in my case, is a most definite "Yes."
</p>

<p>
When I'm not writing articles for IBM developerWorks or being a new dad, I'm
feverishly working on the next release of Gentoo Linux, along with my skilled
team of volunteers. And, yes, Gentoo Linux has its own Web site (see
Resources). As of right now (March 2001), our Web site isn't that special;
that's because we don't spend much time working on it because we're generally
engrossed in improving Gentoo Linux itself. Sure, our site does have several
admittedly cute logos that I whipped up using Xara X (see Resources), but when
you look past the eye candy, our site leaves a lot to be desired. Maybe yours
does too. If so, I have one thing to say to you -- welcome to the club.
</p>

</body>
</section>
</chapter>

<chapter>
<title>www.gentoo.org</title>
<section>
<body>

<p>
In our case, our Web site dilemma exists because our project has been growing,
and our Web site hasn't. Now that Gentoo Linux is approaching the 1.0 release
(when it'll be officially ready for non-developers) and is growing in
popularity, we need to start seriously looking at how our Web site can better
serve its users. Here's a snapshot of www.gentoo.org:
</p>

<figure link="/images/docs/l-redesign-01.gif" 
caption="The current (March 2001) state of affairs at www.gentoo.org"/>

<p>
As you can see, we have all the bare essentials -- a description of Gentoo
Linux, a features list, a daily Changelog (automatically updated thanks to
Python), and a bunch of important links (to the download sites, to our mailing
list sign-up pages, and to cvsWeb). We also have links to three documentation
resources -- the Gentoo Linux Install Guide and Development Guides, and
Christian Zander's NVIDIA Troubleshooting Guide.
</p>

<p>
However, while the site seems O.K., we're missing a lot of things. The most
obvious is documentation -- our installation and development guides need a lot
of work. And then we need to add an FAQ, new links, new user information...the
list is endless.
</p>

</body>
</section>
<section>
<title>Content vs. display</title>
<body>

<p>
And now we come to our second problem. Right now, all of our work is done in
raw HTML; I hack away at the index.html file until it looks O.K. Even worse,
our Web documentation is written in raw HTML. This isn't a good thing from a
development perspective because our raw content (consisting of paragraphs,
sections, chapters) is garbled together with a bunch of display-related HTML
tags. This, of course, makes it difficult to change both the content and the
look of our site. While this approach has worked so far, it is bound to cause
problems as our site continues to grow.
</p>

<p>
Clearly, we need to be using better technologies behind the scenes. Instead of
using HTML directly, we need to start using things like XML, XSLT, and Python.
The goal is to automate as much as possible so that we can add and expand our
site with ease. If we do our job well, even major future changes to our site
should be relatively painless.
</p>

</body>
</section>
<section>
<title>A strategy!</title>
<body>

<p>
It was clear that we had a lot of work ahead of us. In fact, there was so much
to be done that I didn't know where to begin. Just as I was trying to sort out
everything in my head, I came across Laura Wonnacott's "Site Savvy" InfoWorld
column (see <uri link="#resources">Resources</uri>). In it, she explained the
concept of "user-centric" design -- how to improve a Web site while keeping the
needs of your target audience (in this case, Gentoo Linux users and developers)
in focus. Reading the article and taking a look at the "Handbook of
User-Centered Design" link from the article helped me to formulate a strategy
-- an action plan -- for the redesign:
</p>

<ol>
  <li>
    First, clearly define the official goal of the Web site -- in writing.
    What's it there for, and what's it supposed to do?
  </li>
  <li>
    Identify the different categories of users who will be using your site --
    your target audience. Rank them in order of priority: Which ones are most
    important to you?
  </li>
  <li>
    Set up a system for getting feedback from your target audience, so they can
    let you know what you're doing right and wrong.
  </li>
  <li>
    Evaluate the feedback, and use it to determine what parts of the site need
    to be improved or redesigned. Tackle high-priority sections first.
  </li>
  <li>
    Once you've selected the part of the site to improve, get to work! During
    your implementation, make sure that the content and design of the new
    section caters specifically to the needs of your target audience and fixes
    all known deficiencies.
  </li>
  <li>
    When the section redesign is complete, add it to your live site, even if it
    has a look that's markedly different from your current site. This way, your
    users can begin benefitting from the newly redesigned section immediately.
    If there's a problem with the redesign, you'll get user feedback more
    quickly. Finally, making incremental improvements to your site (rather than
    revamping the whole site and then rolling it out all at once -- surprise!)
    will help prevent your users from feeling alienated by your (possibly
    dramatic) site changes.
  </li>
  <li>After completing step 6, jump to step 4 and repeat.</li>
</ol>

</body>
</section>
<section>
<title>The mission statement</title>
<body>

<p>
I was happy to discover that we already had step 3 in place. We had received
several e-mail suggestions from visitors to the site, and our developer mailing
list also served as a way of exchanging suggestions and comments. However, I
had never really completed steps 1 or 2. While the answers may seem obvious, I
did find it helpful to actually sit down and write out our mission statement:
</p>

<p>



-- 
gentoo-doc-cvs@g.o mailing list