Dokumetntacja.

[Tomasz Kłoczko]

On Fri, 6 Oct 2000, Lukas Dobrek wrote:
[..]
> To zaklada ze mamy perfekcyjnie przygotowany docbook i okolice. Ja sie na tym 
> w zasadzie nie znam ale wierze, ze tak jest. Choc pamietam ze albo tu albo 
> na ircu ktos reportowal ostatnio jakies problemy.

Jezeli są jakieś anomalie to o takich rzeczach powinien wiedzieć Rafał i
każdego kto sie na takie anomalie podczas przetwarzanai dokumentacji
sgml/xml sie natknie prosiłbym o podsyłanie takich informacji Rafałowi
(<klakier w pld.org.pl>).

> Nie zmienia to postaci rzeczy ze zgadzam sie z toba ze jak jest
> dokumentacja w docbooku to nalezy ja dostarczac w docbooku. Nadal
> jednak pozostake problem pakietow ktore nie maja dokumenatcji
> napisanej w docbook. Mozna liczyc, na to, ze w ktoryms momencie
> autorzy napisza dokumentacje w SGML ale to napewno chiwle potrfa a
> pakiety trzeba pakowac teraz.

Tu jest kwestia w dopracowywaniu jakiś narzędzi do konwersji na sgml czy
też wykonujących taka konwersje wstepną (bo jednoznacznie nie da się tego
oczywiście zrobić). Zapewne jakieś wsepne pzretworzenie tego typu
dokumentu + jakieś drobne poprawki po takim pzrefiltrowaniu i podesłanie
tego maintainerowi pakietu powiny być dobrze widzaine. W ten sposób mozan
to próbować zmieniać. jezeli beziemy mieli pokompletowane jakeiś narzędzia
które coraz sprawniej bendą wspomagać takie ruchy to zapewne i nam bedzie
łatwiej i także wkonywanie zmian na skalę bardziej masową moze być
łatwiejsze.
Zapewne kluczowe może być w tym momencie opracowanie aplikacji która
będzie umożliwiała edycję dokumentacji sgml/docbook w postaci nieco
bardziej strawne. O próbie podejścia do czegoś takiego rozmawialiśmy już z
Rafałem. Pierwszym etapem mogłoby być opracowanie aplikacji która
posłużyłaby do bezpośredniego przeglądanai/wyszukowanai informacji
zgromadzonych w dokumentacji HOWTO. Potem możnaby do tego dołożyć sprawy
zwiazwne z edycją.
Nie jest to proste i wykonalne w krutkiej skali czasu ale też i planowanie
czegoś na krutki dystans to jest to czego coraz bardziej powinniśmy
unikać w skli większych porcji zasobów. Ważne jest to, że jest to poprostu
potrzebne i przydatne i że w zasadzie nie widać żeby ktoś próbował cos w
tym kierunku robić - czyli zdajac sobie sprawe z tego typu braku chyba
najbardziej nadajemy sie jako zespół do próby zmierzenai sie z tematem.

> > Stwarzanie warunków w których instalacja dokumentacji staje sie bardziej
> > skomplikowana niz to byc moze w optymalnych warunkach lub kiedy
> > niepotrzebnie zaczyna sie to komplikowac nie powinno byc naszym celem i to
> > juz ze wzgledu na to ze tejze dokumentacji sami od czasu do czasu
> > potrzebujemy.
> 
> Ale nalezy optymalizowac nie tylko latwosc instalacji ale jeszcze funkcjonalnosc.

Owszem ale zauważ, że przy takim podejściu funkcjonalność daje się
stosunkow prosto zachować.

> Najprosciej pod wzgledem instalacji jest wogule nie dostarczac dokumentacji. 

To byłoby piłowanie gałezi na której się siedzi.

> Gdyby dostarczac dokumentacje we wszystkich mozliwych formatach to 
> optymalizaowalo by sie wlasnie funkcjonalnosc. Ja proponuje optymalizowac 
> funkcje tych dwoch zmiennych. 

Tyle tylko, że generowanie wszystkich możliwych czy kilku możliwych
formatów wyjściowych w pakietach jest IMHO nieopłacalne na dłuższą
metę. Owszem teraz zaspakaja potzreby ale wobec perspektywy próby
roziazanai tego inaczej czas na zaspokojenie doraźnych celów wydaje sie
czasem stracony (post factum).

kloczek
-- 
-----------------------------------------------------------
*Ludzie nie mają problemów, tylko sobie sami je stwarzają*
-----------------------------------------------------------
Tomasz Kłoczko, sys adm @zie.pg.gda.pl|*e-mail: kloczek w rudy.mif.pg.gda.pl*