RE: Dokumentacja (długie, ale przeczytajcie proszę)

[Jacek Konieczny]

On Mon, Nov 01, 1999 at 01:06:13AM +0100, Tomasz Kłoczko wrote:
> > Ale praktycznie jest to niemożliwe. Za dużo roboty. 
> > Np. w moim podręcznym testowym systemie na 297 pakietów jest 5668 plików 
> > z dokumentacją.  Większość trzebaby przełożyć. 
> 
> Jeżeli chcesz to zrobić w jednym podejściu owszem. Jeżeli wyznaczysz to   
> jako kierunek w którym należy iść to juz jest to mniej obciązające.
> Pierwszrego podejścia nikt chyba o zdrowych zmysłach nie będzie
> poroponował.

Mnie się ten pomysł wogóle nie podoba. A co przy uaktualnieniach
dokumentacji? W końcu ludzie w PLD zajmowali by się tylko dokumentacją.
Z drugiej strony, gdy twórcy programów tworzyli do nich dokumentację
świadomie wybierali narzędzia i format i napewno mieli jakieś powody.
Osobiście wolałbym, żeby PLD zawierało w miarę zunifikowany interfejs do
najpopularniejszy formatów dokumentacji, a samą dokumentację zostawiało
w formie w której jest rozprowadzana. 
Moglibyśmy jedynie coś zmieniać, tam gdzie jest możliwość wyboru
formatu.

A co do dokumentacji, którą musimy zrobić do PLD - tu trzeba określić
standard i sie jego trzymać.
Mnie osobiście na JWL'99 przekonano do PDF-a, choć ma on swoje wady
(trudno przeszukiwać). Napewno SGML jest dobrym kierunkiem - ale co
dalej to nie jestem pewien.

Według mnie dokumentacja powinna wyglądać mniej więcej tak:
  - do każdej komendy przynajmniej minimalna strona "man"
  - do każdego pakietu/zagadnienia jakiś HTML czy PDF
  - z rzeczy które my tylko pakujemy - zostawiamy jak jest, w przypadku
  mnogości formatów zostawiamy man/info i HTML

Pozdrowienia,
         Jacek
-- 
+---------+--------------------------------------------------------+
!      ,  !            Jacek Konieczny, Gliwice, Poland            !      
! Jajcus  !   email: jajcus w zeus.polsl.gliwice.pl, jacek w kde.org   !
!         ! ICQ# 7149127                           WWW: none (yet) !
+---------+--------------------------------------powered-by-Linux--+