Dokumentacja: raport

[Rafał Kleger-Rudomin]

Widzę że jest czeski film z dokumentacją znowu, wiec się poczuwam 
by parę rzeczy wyjaśnić:


Stan obecny
===========

Ważniejsze spośród istniejących dokumentów powstałych w ramach PLD i okolic:

        1 Podręcznik developera PLD (pl)
        2 Wprowadzenie do CVS (pl)
        3 Stary opis instalacji dla prowizorki (pl, en)
        4 Założenia nowego instalatora (en)
        5 Mój wstęp do XEmacsa (pl)
        6 PLD admin manual (en)
        7 Ogólne informacje na stronie www.pld.org.pl (pl, en)
        8 PLD installation manual (serkowy opis do noweg installera) (en)
        9 Dzimiego opis jadra (?)
       10 Faq na irc.pld.org.pl (pl)

Ważniejsze "repozytoria" tych dokumentów:

Stary moduł doc:
        Znajdują się tu dokumenty 1-6

Moduł PLD_www_res:
        Znajduje się tu "dokument" 7

Moduł PLD-Guide:
        Na PLD-Guide składają się obecnie dokumenty 7, 8, 6 oraz 4, tzn 
        są tam przeniesione informacje ze strony www (nie wiem czy wszystkie), 
        serkowy opis instalacji (ze screenszotami), oraz admin manual 
        i założenia installera

Reszta dokumentów znajduje się w miejscach różnych.


Cele i założenia
================

Oto zgrubsza cele i założenia jakie przyświecają mi kiedy zajmuję sie 
dokumentacją PLD:

0. Dokumentację należy przede wszystkim stworzyć, jednak należy mieć na
   uwadze że jest to tylko niewielka część pracy. Dużo cięższym 
   i o wiele bardziej niewdzięcznym zajęciem jest jej _utrzymywanie_.
   W związku z tym należy uczynić tę czynność maksymalnie prostą. Temu
   służą kolejne punkty:
1. Dokumentacja jest składowana w _jednym miejscu_
2. Dokumentacja jest tworzona w jednym formacie i jest nim DocBook XML2. 
3. Owo jedno miejsce jest jedynym _źródłem_ dokumentacji, 
   wszelkie postaci prezentacyjne (czy to html czy inne), mogą być
   w dowolnym momencie _wygenerowane_ z tego źródła. Wszelkie ręczne 
   przetwarzanie, tudzież jednorazowe wygenerowanie postaci prezentacyjnej 
   i jej osobne utrzymywanie jest niedopuszczalne [*]
4. Pod dokumentację podciągam również stronę www.pld.org.pl, która dotychczas 
   żyła własnym życiem, pozostając wiecznie nieaktualną, za to ze
   zmieniającym się designem w miarę przychodzenia i odchodzenia
   kolejnych webmasterów.

[*]  nie stać nas na to, jest to niewygodne, męczące, i na dłuższą metę
     niemożliwe do upilnowania by dwa lub więcej źródeł były aktualne.


Realizacja
==========

Pierwotnie cele realizowałem trzymając dokumentację w module doc.
Jednak nie było w tej hierarchii strony www. Poza tym był to zbiór
osobnych dokumentów z których nie wszystkie (jak np opis XEmacsa)
były rzeczywiście związane z PLD.

Aktualnie realizowana serkowa koncepcja jest dużo bardziej radykalna:
Skupić wszelkie doce związane z PLD w jednym dokumentcie
o nazwie PLD-Guide. Dokument ten został założony w ramach 
LDP (cvs://LDP/guide/docbook/PLD-Guide), dostępny również jako osobny
moduł (cvs co PLD-Guide).

Reszta dokumentów nie związanych bezpośrednio z PLD (XEmacs i 
wprowadzenie do CVS), może być hostowana osobno (np zostać u mnie na 
koncie na team jak dotychczas)

Stan prac
=========

Akualny PLD-Guide w html można obejrzeć sobie tu (bardzo draft):

        http://team.pld.org.pl/~klakier/PLD-Guide/ 

Michał Moskal zrobił jakieś ładniejsze skrypty których wynik jest tu:

        http://ep09.kernel.pl/~malekith/pldg/html/toc.html

(...ale jeszcze nie widziałem tego bo ep09 nie odpowiada).


Problemy
========

Podstawowy problem to brak współpracy ze strony zespołu.
PLD-Guide aktualnie pisze głównie Serek oraz ja. Ostatnio udało mi się namówić
bluesa oraz wojrusa żeby napisali po rozdziale (dzięki raz jeszcze!). 
Dzimi ma wszystko w nosie i klepie o kernelu po swojemu. 

Trudno się nawet dowiedzieć na liście o wszystkie możliwości jakie drzemią 
w naszych rc-skryptach żeby móc to opisać.


Do zrobienia
============

- przetłumaczyć na angielski i dołączyć Podręcznik Developera
- rozwijać część PLD admin guide
- namówić więcej osób do współpracy
- podmienić www.pld.org.pl na htmlowy wynik PLD-Guide, ewentualnie
  zostawić tylko ręcznie dzierganą stronę główną.
- regularnie informować o istnieniu i postępach PLD-Guide


Pozdrawiam,
Rafał

-- 
Rafał Kleger-Rudomin (klakier w pld.org.pl)