Witam
Zamieszczam poniżej treść listu do magazynu programistamag.pl pt:
"Propozycja artykułu: procesory dokumentacji kodów źródłowych i tworzenia
dokumentacji systemów informatycznych"

Celem przedyskutowania tego tematu (bo może coś źle pojmuję, albo nie w pełni, albo
czegoś wcale nie uwzględniam). Ten post adresuję głownie do czytelników pisma.

pozdro
Szyk

Oto treść listu:
W najnowszym numerze Programisty jest artykuł o... hmm... systemie Latex... Co jest z
nim nie tak? Ano to, że to jest nie dzisiejsze podejście do tworzenia publikacji.
Jakie jest podejście współczesne? Ano takie, że piszemy dokument w danym formacie i
generujemy programem lub skryptem wersję w danym formacie docelowym, np. Html, Pdf,
Doc, Ppt (prezentacje), Flash (np. do realizacji dostępu ekskluzywnego, czyli dla
ograniczonego kręgu (płacących) odbiorców). W sumie to dość szokujące, że wydawnictwo
programistyczne nie rozumie ducha czasów, choć samo musi się mierzyć z takimi
problemami jak różne formaty docelowe dokumentacji (w tym wypadku czasopisma).

Co ciekawe jest potrzeba tworzenia dokumentacji programistycznej bibliotek w formacie
umożliwiającym wiele formatów docelowych. Jest tak, gdyż czymś oczywistym jest
dokumentacja w Internecie (dostęp przez przeglądarkę) i na dysku (dostęp przez
dedykowaną aplikację). To jest obecnie standard! I wiedza o dostępnych rozwiązaniach
i ich mocnych i słabych stronach jest potrzebna. Sztandarowym rozwiązaniem jest
Doxygen, w bibliotece Qt natomiast jest QDoc. Może są też inne poważne rozwiązania.
Na pewno mają wady i zalety - i to należy wyłuskać i podać! Tak byśmy mogli TWORZYĆ
ŚWIADOMIE profesjonalne rozwiązania!

A nie jakieś pierdum-pierdum o tym, że jest jakiś Latex i można w nim używać
znaczników do modyfikowania wyglądu - to widzę po samych skrenszotach! Ten artykuł
nawet nie próbował podjąć tematu edytorów, bo autor bezradnie stwierdza: "W sumie to
trudno powiedzieć który jest najlepszy..." - Jak nie ma miejsca na rzeczowy artykuł
to nie wstawiajcie "zapchaj dziury" bo to kompromitacja, nawet mimo "lekkiego
charakteru" numeru wakacyjnego!

[[[ NAWIASEM MÓWIĄC: ]]]

to powyższe jest moją opinią i możecie myśleć, że jestem stronniczy (i mielibyście
rację bo obstaję przy swoich interesach). Dlatego radziłbym się pytać
"praktykujących" programistów:

1. Czego by się chcieli dowiedzieć? (i na co nie mają czasu by "przewąchać temat")

2. Jakiej wiedzy im brakuje? (o co się potykają na co dzień)

3. Co robią na co dzień i z czego nie są zadowoleni? (bo czują, że można by lepiej,
ale nie wiedzą jak)

I proszę: nie piszcie mi, że wasz "expert" od C++ nie uznaje Qt, więc dla nas ona nie
istnieje, bo to nie jest z M$, bo takie podejście Was odrealnia i w końcu Was
załatwi. Piszę to, bo uważam, że magazyn o programowaniu jest bardzo potrzebny...

I jak brakuje Wam rzetelnych autorów (a nawet gdyby wszyscy byli rzetelni) to waszym
podstawowym obowiązkiem jest CIĄGŁE POSZUKIWANIE LEPSZYCH AUTORÓW - to powinien być
element strategi ciągłego dążenia do nie możliwego - czyli do ideału i najwyższej
jakości. Gdzie szukać?!? Ludzie wiedzą kto wyróżnia się w społeczności (scena, grupy
dyskusyjne, fora, środowiska akademickie - tam też wielu ludzi pracuje w firmach na
część etatu - więc nie są całkiem odrealnieni) i nie powinniście się ograniczać do
autorów polskich (choć może jest to uzasadnione z przyczyn ekonomicznych - choć może
i za wschodnią granicą są jacyś sensowni eksperci - w końcu Helion publikował ich
książki i w dodatku ponoć Ruski mają najwyższą proporcję ludzi z wyższym
wykształceniem - to musi dawać jakieś efekty!).

W sumie nie wiem jaki sens jest publikowanie artykułów prezentujących "helo word" w
różnych językach czyli po nowemu: "frame workach" gdzie te programy mają dla nie
poznaki formę "wyświetl okno z kontrolkami" - przecież to jest banał (tak, tak,
artykuł o Xwt z najnowszego numeru - w dodatku co to za "wieloplatfomowość"
ograniczona do WinDos i MacOs). Potrzebne są informacje o sprawdzonych "scenariuszach
użycia" w jakichś mniej banalnych projektach. Wydajność, bezpieczeństwo,
współbieżność, modularność, rozszerzalność (skalowanie architektury). Choć nie jestem
zwolennikiem technologii M$ to ukazanie silnych stron architektury .Net było by
ciekawe - oraz jak wygląda na jego tle konkurencja (C++, C, Java, Delphi, Www).

Skoro już jesteśmy przy sprawdzonych rozwiązaniach w praktycznych projektach.
Przecież jest wiele dużych projektów Open Source (tak, tak, wiem, wiem to znowu nie
M$...). Czy widzieliście tą stornę:

http://aosabook.org/en/index.html ?!? Na niej są opisane prawdziwe projekty - ich
mocne i słabe strony, to co się sprawdziło i co działa. To nie są dyrdymały i
dywagacje - TO JEST PRAWDA!!! Nie mówię, że macie tłumaczyć te książki, ale może
mogłyby być jakimś argumentem za daną technologią/rozwiązaniem?