Riprogettare gentoo.org, Parte 1: La rinascita di un sito web

1.  Un'orda indisciplinata

Sviluppatori di software, posso fare una domanda? Perchè, sebbene molti di noi siano profondi conoscitori delle tecnologie web come HTML, CGI, Perl, Python, Java e XML, i nostri siti web (quelli che descrivono i nostri preziosi progetti di sviluppo) sembrano concepiti da un'orda iperattiva di dodicenni? Perchè, oh perchè è cosi?

Potrebbe essere che lasciamo il nostro sito web marcire, mentre sperperiamo il nostro prezioso tempo lavorando sul nostro progetto software? La risposta è, almeno nel mio caso, un decisamente "Si".

Quando non sto scrivendo articoli per IBM developerWorks o diventando un nuovo papà, lavoro ferventemente alla prossima release di Gentoo Linux, assieme al mio gruppo di esperti volontari. Gentoo linux ha un proprio sito web. Ad oggi (Marzo 2001), il nostro sito web non è niente di speciale perchè non passiamo molto tempo lavorando su di esso esiamo completamente assorbiti nel migliorare Gentoo Linux. Certamente il nostro sito ha parecchi graziosi logo realizzati con Xara X (si veda Risorse), ma se il vostro sguardo va oltre la vostra punta del naso, il nostro sito lasci amolto a desiderare. Forse anche il vostro. Se cosi fosse, ho una cosa da dirvi: benvenuti nel club.

2.  www.gentoo.org

Nel nostro caso, abbiamo un problema perchè il nostro progetto è cresciuto, mentre il nostro sito web no. Ora che Gentoo Linux sta arrivando alla release 1.0 (quando sarà ufficialmente pronta per gli utenti) e sta crescendo in popolarità, dobbiamo seriamente ripensare come il nostro sito web può meglio servire i suoi utenti. Qui c'è uno snapshot di www.gentoo.org:

Figura 2.1: Lo stato attuale (Marzo 2001) di www.gentoo.org

Come potete vedere, noi abbiamo tutto l'essenziale: una descrizione di Gentoo Linux, una lista di articoli, un Changelog giornaliero (automaticamente aggiornato grazie a Python) e un gruppo di importanti link (al sito per il download, alle pagine delle nostre mailing-list, al sito cvs). Ci sono anche i collegamenti a tre documenti: la Gentoo Linux Install Guide, alla Development Guides e alla NVIDIA Troubleshooting Guide di Christian Zander.

Anche se il sito sembra ok, mancano molte cose. La più ovvia è la doocumentazione, l'installazione di Gentoo Linux e il suo sviluppo necessitano molto lavoro. Inoltre abbiamo bisogno di aggiungere le FAQ, nuovi link, nuove informazioni per gli utenti... e la lista potrebbe continuare.

Contenuti vs. Grafica

E ora vediamo il nostro secondo problema. Ad oggi, tutto il nostro lavoro è fatto in puro HTML e ho lavorato sul file index.html fintanto che sembrasse ok. Ancora peggio: la nostra documentazione web è scritta in puro HTML. Questa non è una buona cosa in una prospettiva di sviluppo, perchè i nostri contenuti (paragrafi, sezioni e capitoli) si ingarbugliano con un moltissimi tag HTML relativi alla grafica. Questo, naturalmente, rende difficile cambiare sia i contenuti che la grafica del sito. Anche se questo approccio ha funzionato a lungo, è causa di problemi se il nostro sito vuole continuare a crescere.

Chiaramente dobbiamo utilizzare le migliori tecnologie sulla scena: invece di usare direttamente HTML, è necessario iniziare ad usare XML, XSLT e Python. L'obbiettivo è automatizzare il più possibile cosi da poter espandere il nostro sito facilmente. Se dovessimo lavorare bene, ogni cambiamento futuro del nostro sito dovrebbe essere relativamente indolore.

Una strategia!

Era chiaro che avessimo molto lavoro davanti a noi. Infatti, c'era cosi tanto da fare che non sapevo da dove iniziare. Proprio mentre stavo cercando di mettere ordine nella mia mente, venni a conoscenza della rubrica su InfoWorld, "Site Savvy" di Laura Wonnacott (si veda Risorse). Laura spiega il concetto della progettazione orientata all'utente (User-Centered Design): come realizzare un sito web centrando le necessità dei suoi principali utilizzatori, il target (in questo caso, gli utenti e gli sviluppatori di Gentoo Linux). La lettura dell'articolo e del "Handbook of User-Centered Design", collegato all'articolo, mi ha aiutato a formulare una strategia (un piano d'attacco) per la riprogettazione:

1. Primo, definire in modo chiaro l'obiettivo del sito web (e scriverlo). Per quale motivo c'è e a che cosa si suppone debba servire?
2. Individuare le differenti categorie di utenti che useranno il vostro sito (i destinatari). Ordinarle in ordine di importanza. Quali sono le più importanti per voi?
3. Pensare ad un sistema per ottenere commenti dai vostri utenti, cosi che possano far sapere cosa è giusto e cosa è sbagliato.
4. Valutare i commenti e usarli per determinare quali parti del sito necessitano di essere migliorate o riprogettate. Affrontate prima le sezioni più importanti.
5. Una volta selezionata la parte del sito da migliorare, mettevi al lavoro! Durante la scrittura, siate sicuri che i contenuti e il design delle nuove sezioni rispondano specificatamente alle necessità dei vostri utenti e risolvete tutte le carenze conosciute.
6. Quando una sezione riprogettata è completa, aggiungetela al vostro sito, anche se ha un look marcatamente differente dal vostro sito. In questo modo, i vostri utenti possono beneficiare subito della nuova sezione riprogettata. Se ci sono dei problemi con il nuovo design, potrete ottenere commenti più velocemente. Inoltre, realizzare miglioramenti parziali al sito (invece di rimodernare l'intero sito e sostituirlo tutto in una volta, sorpresa!) vi aiuterà a prevenire sentimenti di rifiuto dei vostri utenti per i vostri (magari drammatici) cambiamenti.
7. Dopo aver completato il sesto passo, tornate al quarto e ricominciate.

La dichiarazione d'intenti

Ero felice di scoprire che noi avevamo già fatto il terzo punto. Avevamo ricevuto parecchie e-mail di suggerimenti dai visitatori del sito e la nostra mailing list per sviluppatori serviva anche come modo per scambiare suggerimenti e commenti. Tuttavia, non avevo mai realmente completato il primo e il secondo punto. Mentre le risposte potevano sembrare ovvie, ho trovato utile sedermi e scrivere la nostra dichiarazione d'intenti:

www.gentoo.org esiste per assistere quelli che usano e sviluppano Gentoo Linux, fornendo importanti e aggiornate informazioni su Gentoo Linux e Linux in generale, con particolare attenzione sull'installazione, l'uso, l'amministrazione e lo sviluppo di Gentoo Linux. Il sito dovrebbe anche fornire importanti news per gli utenti e gli sviluppatori di Gentoo Linux. www.gentoo.org ha come scopo secondario di soddisfare le esigenze degli utenti potenziali di Gentoo Linux, fornendo le necessarie informazion per decidere perchè Gentoo Linux è giusta per loro.

I destinatari

Fino ad ora tutto bene. Ora il secondo punto, definire i nostri destinatari:

www.gentoo.org ha tre tipi di destinatari: gli sviluppatori, gli utenti e i potenziali utenti. Mentre nessun gruppo è in assoluto più importante di un altro, le necessità degli sviluppatori hanno la nostra maggiore priorità, seguiti dagli utenti e infine dai potenziali utenti. Questo perchè Gentoo Linux è al momento in fase di sviluppo. Quando Gentoo Linux raggungerà la versione 1.0, gli utenti e i potenziali utenti diventeranno anche loro prioritari.

Commenti e suggerimenti

Ok, ora è il momento di valutare i suggerimenti e i commenti che abbiamo raccolto:

Nei mesi precedenti, abbiamo ricevuto molti suggerimenti dai visitatori del sito web. Ovviamente, le persone chiedevano migliore documentazione, sia per sviluppatori che per utenti. Parecchi sviluppatori chiedevano se fosse possibile creare una mailing list che servisse esclusivamente per seguire il CVS.

Curiosamente, abbiamo ricevuto un paio di email che chiedevano se Gentoo Linux fosse un prodotto commerciale o libero. Mi chiedevo se fosse dovuto al nostro logo principale, che è scritto con "Gentoo Technologies, Inc." (il nostro nome legale), e le persone assumevano che avessimo un obbiettivo commerciale. Modificando il nostro logo cosi che si legga "Gentoo Linux" e aggiungendo un piccolo paragrafo sulla pagina principale spiegando che siamo un progetto free-software non dovremmo più creare dubbi.

La lista dei miglioramenti

Ok, ora trasformiamo i suggerimenti in una possibile lista di miglioramenti:

• Rimodernare la pagina principale
  • Realizzazione: un logo aggiornato e aggiungere un paragrafo sul free software
  • Obiettivo: chiarire che siamo un progetto free software
  • Destinatari: utenti potenziali
  • Difficoltà: media
• Migliorare la documentazione di base per gli utenti
  • Realizzazione: nuovo sistema XML/XLST, documentazione completa
  • Obiettivo: rendere più semplice installare Gentoo Linux
  • Destinatari: nuovi utenti
  • Difficolta: media
• Migliorare, creare documentazione per sviluppatori
  • Realizzazione: nuovo XML/XLST, guida CVS, guide per svipppatori, guida per Portage
  • Obiettivo: aiutare i nostri sviluppatori a fare un grande lavoro
  • Destinatari: sviluppatori
  • Difficolta: difficile
• Aggiungere una mailing-list CVS
  • Realizzazione: usare l'esistente mailman mailing list manager
  • Obiettivo: migliorare le informazione ai nostri sviluppatori
  • Destinatari: sviluppatori
  • Difficolta: facile

Una selezione!

Due cose sono saltate fuori dalla lista, per differenti ragioni. La prima è la mailing list CVS: questa non è preuccupante perchè è facile da implementare. Spesso ha senso realizzare le cose più facili per prime, cosi che gli utenti possano beneficiarne subito.

La seconda grande cosa uscita dalla lista è la necessità di avere documentazione per gli sviluppatori. Questo è un progetto a lungo termine che richiederà molto lavoro. Durante le conversazioni con gli altri sviluppatori ci siamo trovati in accordo su un approccio con XML/XSL che appare la giusta soluzione.

Il prototipo XML/XSL

Per aiutare l'inizio del processo, ho sviluppato un prototipo di sintassi XML da usare per la documentazione online. Usando questa sintassi XML (chiamata "guide"), la nostra documentazione potrà essere chiaramente organizzata in paragrafi, sezioni e capitoli (usando XML tag come <section>, <chapter>, etc.) mentre rimane libero da ogni altro tag di formattazione. Per creare un HTML da visualizzare sul nostro sito, ho creato un prototipo di trasformazione XSL. Usando un processore XSLT come Sablotron, la nostra guida scritta in XML può essere convertita in un file HTML cosi:

devguide.xml + guide.xsl ---processore XSLT---> devguide.html

La grande cosa dell'approccio con XML/XLST è la separazione tra i nostri contenuti (XML) dalle informazioni per la visualizzazione contenute nel file guide.xls (XLS). Se abbiamo la necessità di aggiornare il look delle pagine web, noi semplicemente modifichiamo il file guide.xls e processiamo tutti i nostri file XML attraverso il processore XSLT (Sablotron), creando le pagine HTML aggiornate. Se abbiamo la necessità di aggiungere piccoli capitoli alla guida di sviluppo, possiamo modificare devguide.xml. Una volta fatto, processiamo il file XML attraverso Sablotron ed otterremo un devguide.html interamente formattato con i parecchi capitoli aggiunti. Pensiamo all'XML come ai contenuti e XSLT come ad una macro di formattazione per la visualizzazione.

Mentre il nostro intero team è convinto che XML/XLST è la strada da percorrere, non siamo ancora daccordo su una sintassi XML ufficiale. Achim, il nostro sviluppatore capo, suggeriva che noi dovevamo usare docbook per processare la nostra sintassi XML. Tuttavia, il formato del prototipo della guida XML ha guidato la scelta del processo. Poichè noi sviluppatori siamo quelli che useranno XML/XSL giornalmente, è importante scegliere una soluzione che sia confortevole e che venga incontro a tutte le nostre esigenze. Nel mio prossimo articolo, dovrei avere un documento XML/XSL da mostrarvi.

Demo tecnologica: pytext

Per la maggior parte, il nostro sito web corrente non sta usando nessuna nuova o super-bella tecnologia di valore che sono state descritte. C'è una eccezione degna di nota: il nostro piccolo interprete Python integrato (pytex).

Come molti di voi, sono un grande fan di Python e lo preferisco molto agli altri linguaggi di scriptting, cosi quando è necessario aggiungere alcuni contenuti dinamici sul nostro sito web, io naturalmente cerco di usare Python. Come probabilmente sapete, quando si codifica un contenuto dinamico in HTML, è molto conveniente integrare i comandi del linguaggio dentro HTML, invece che fare diversamente, ma è necessario di un inteprete Python integrato che possa prendere un file come questo:

<p>
Yeah, sure; I got some questions:<br>
<!--code
names=["bob","jimmy","ralph"]
items=["socks","lunch","accordion"]
for x in items:
for y in names:
print "Anyone seen",y+"'s",x+"?<br>"
-->
See, told you so.

....e trasformarlo in questo:

<p>
Yeah, sure; I got some questions:<br>
Anyone seen bob's socks?<br>
Anyone seen jimmy's socks?<br>
Anyone seen ralph's socks?<br>
Anyone seen bob's lunch?<br>
Anyone seen jimmy's lunch?<br>
Anyone seen ralph's lunch?<br>
Anyone seen bob's accordion?<br>
Anyone seen jimmy's accordion?<br>
Anyone seen ralph's accordion?<br>
See, told you so.

Qui c'è il codice sorgente per pytex:

#!/usr/bin/env python

# pytext 2.1
# Copyright 1999-2001 Daniel Robbins
# Distributed under the GPL

import sys

def runfile(myarg):
   "interprets a text file with embedded elements"
   mylocals={}
   try:
      a=open(myarg,'r')
   except IOError:
      sys.stderr.write("!!! Error opening "+myarg+"!\n")
      return
   mylines=a.readlines()
   a.close()
   pos=0
   while pos<len(mylines):
      if mylines[pos][0:8]=="<!--code":
  mycode=""
  pos=pos+1
  while (pos<len(mylines)) and (mylines[pos][0:3]!="-->"):
       mycode=mycode+mylines[pos]
       pos=pos+1
  exec(mycode,globals(),mylocals)
       else:
  sys.stdout.write(mylines[pos])
       pos=pos+1

if len(sys.argv)>1:
   for x in sys.argv[1:]:
       runfile(x)
   sys.exit(0)
else:
   sys.stderr.write
     ("pytext 2.1 -- Copyright 1999-2001 Daniel Robbins. ")
   sys.stderr.write
     ("Distributed under the\nGNU Public License\n\n")
   sys.stderr.write
     ("Usage: "+sys.argv[0]+" file0 [file1]...\n")
   sys.exit(1)

Come pytex lavora

Ecco come lavora. Pytex legge ogni linea e, il più delle volte, ogni input è semplicemente ripetuta allo stdout. Se pytex incontra una linea che inizia con <!--code, i contenuti di ogni linea fino a --> sono aggiunti alla stringa chiamata mycode. Pytex quando esegue le stringa mycode usa la funzione exec() interna, creando effettvamente un interprete Python integrato.

C'è qualcosa di veramente bello in questa particolare implementazione: exec() è chiamato in modo che tutte le modifiche dei namespace globali e locali sono salvati. Questo rende possibile importare un modulo o definire una variabile in un blocco integrato e poi accedere a questo oggetto in un blocco successivo, come questo esempio chiaramente dimostra:

<!--code
import os
foo=23
-->

Hello

<!--code
print foo
if os.path.exists("/tmp/mytmpfile"):
print "it exists"
else:
print "I don't see it"
-->

Pratico eh? Il risultato di pytext è una eccellente dimostrazione della potenza di Python e pytex è un utilissimo tool per i fan di Python. Per il nostro sito attuale, noi chiamiamiamo pytext da un cron job, usandolo periodicamente per generare un codice HTML per le nostre variazioni sulla pagina principale.

pytext index.ehtml > index.html

Questo è tutto per ora; ci vediamo la prossima volta quando daremo una occhiata al primo stage della riprogettazione di www.gentoo.org!

3.  Risorse

• Leggete gli altri articoli in questa serie di developerWorks sulla riprogettazione del sito web www.gentoo.org usando tecnologie come XML, XSLT e Python:
  • Nella Parte 2, Daniel mostra il nuovo sistema per la documentazione e programma una mailing list per i CVS-log giornaliera (Maggio 2001).
  • Nella Parte 3, crea un nuovo look per il sito (Luglio 2001).
  • Nella Parte 4, Daniel completa la conversione XML/XSLT, fissa un bug di compatibilità del browser Netscape 4.x e aggiunge un autogenerato XML Changelog al sito (Agosto 2001).
• Se non avete ancora usato python, potete farvi del male da soli. Lo trovate al http://www.python.org.
• La rubrica di Laura Wonnacott's Site Savvy appare regolarmente su InfoWorld.com.
• Controllate Xara.com, la home page di Xara X, un eccellente programma per il disegno vettoriale per Windows. Non troppo grosso e velocissimo, ha la mia personale raccomandazione.
• Impara di più su XSLT con http://www.xslt.com
• Quando ti svegli, controlla Sablotron, un veloce processore XSLY disponibile su Gingerall