Dokumentacja przez www.

[Radosław Kintzi]

On Wed, Jun 12, 2002 at 08:15:08PM +0200, Rafał Kleger-Rudomin wrote:
> > 
> > Jeszcze raz: zapewne każdy z Was widział różne rozwiązania w mniejszym czy
> > większym stopniu służące do zarządzania dokumentacją (ja sam jedyne co
> > widziałem to FAQomatic
> 
> oo to już jakiś konkretny przykład.
> Nie ma _żadnych_ przeciwwskazań by można było dorobić podobny
> piękny interfejs do wielojęzycznego modyfikowania PLD-Guide.
> może być nawet w php z użyciem php-domxml. Nie używałem
> tego ale z opisu wynika że jest to moduł DOM XML.
> Czyli wszystko co byłoby potrzeba do wygodnego zrobienia takowego 
> interfejsu jak ktoś się już rzeczywiście uprze robić w php.
> 
> No więc proszę bardzo ja mam wymagania co do tego systemu,
> (który, coraz bardziej jestem tego pewnien, istnieje dopiero 
> w Twojej wyobraźni i to jeszcze nie do końca): 
> mianowicie chcę żeby backendem był nadal cvs z PLD-guide. 
> Ma być tak: frontend www ma osobne konto w cvs i swoją
> własną autoryzację (żeby każdy piszący nie musiał mieć własnego
> wjazdu do cvs tylko korzystał jedynie z www). Frontend
> prezentuje ładnie treść, pozwala ją edytować i commitować.
> 
> I tyle, skoro już musi być frontend www, niech będzie, ale niech
> korzysta z cvs i xml. Dzięki temu ten sam dokument pozostanie
> dostępny z poziomu dowolnych innych narzędzi.

To jest rozwiązanie, które IMHO warto wprowadzić, bo może przyczynić
się do pozyskania nowych dokumentalistów. 

Inną rzeczą jest dyskusja nad tym czy cvs i xml jako bazodanowy
engin, to technologie odpowiednie.

Każdy dokument xml można przedstawić w postaci drzewa, którego
wierzchołki (różnych typów) mają specyficzne atrybuty i mogą
przechowywać tekst. Strukturę tego dokumentu (jaki wierzchołek
gdzie może/musi wystąpić, jakie musi/może mieć argumenty, oraz
czy może/musi zawierać tekst, czy nie) określa DTP. 

/* Warto sobie uświadomić, że narzędzia do odpytywania o zawartość
dokumentu xmlowego (przykładowe pytania podał blues) budują sobie
takie drzewka. */

Tak więc te dokumenty (które już istnieją) można trzymać w pliku 
tekstowym, lub w postaci drzewa (np. w bazie sql, choć sql to raczej 
do przechowywania drzew raczej się nie nadaje). Można dyskutować, co 
jest lepszym rozwiązaniem. Zaletą xml jest czytelność dla człowieka. 
Drzewo natomiast jest łatwiejsze do przetwarzania automatem. Te jednak 
(drzewo) można zawsze wygenerować (są do tego dostępne narzędzia 
w postaci bibliotek dla różnych języków). Innym kłopotem przy przejściu
z tekstowej do drzewiastej reprezentacji jest konieczność napisania
generatora plików xmlowych, dla tych co to chcą używać vima (a Ci co 
obecnie tworzą dokumentację tego właśnie chcą i dali temu wyraz na 
tej liście).

Jest jeszcze jeden ważny aspekt tworzenia dokumentacji, który może
mieś wpływ na wybór sposobu przechowywania dokumentów. Jest to 
przechowywanie i zarządzanie informacją dodatkową, taką jak np. stan
(zaawansowanie) tłumaczeń. Nie wiem czy mówimy tutaj o tym, co znajduje 
się w module PLD-doc i nie wiem jak ten modół teraz wygląda. Kiedyś jednak 
tam zajrzałem (gdy potrzebowałem przykładu jak pracować z dokumentami) 
i to co tam było, to nic innego jak drzewiasta baza danych z dokumentami. 
Te drzewa kodowane są w postaci katalogów. Nic nie stoi na przeszkodzie,
by w tych katalogach trzymać dodatkowe informacje o stanie dokumentacji.

Jak widać baza danych już istnieje i funkcjonuje całkiem nieźle 
(Ci którzy z niej korzystają nie mają tutaj problemów).
Nie jest to jednak rozwiązanie pozbawione wad. Jedną z nich jest
to że cała baza jest kodowana na dwa sposoby: w postaci katalogów
w systemie plików oraz dokumentów xmlowych (czyli drzewa kodowane
są w dwojaki sposób). Inną jest zapewienie spójności samych danych.
Ciężko bowiem wymagać, by ktoś kto całą noc ślęczał nad tłumaczeniem
jakiegoś doca pamiętał, że należy jeszcze zapisać w odpowiednim miejscu
informację o wprowadzonych zmianach. Tutaj niewątpliwie przydałby się
automat, a ten wymaga reprezentacji na drzewach.

Ponieważ nie zajmuje się dokumentacją nie chcę tutaj rozstrzygać,
czy problemy i korzyści, jakie starałem się zidentyfikować, 
przesądzają o tym czy trud reorganizacji jest warty zachodu.
Wolałbym jednak, by dyskusja toczyła się wokół owych korzyści 
i problemów.

Radek
-- 
mailto:radzio w pld.org.pl
gg:2199600