W dniu poniedziałek, 23 lipca 2018 17:23:49 UTC+2 użytkownik s...@g...com
napisał:
> 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.

Kiedyś kupiłem kilka numerów (nie byłem zachwycony), ale pewnie brakuje
mi kontekstu, bo chyba niezbyt dobrze zrozumiałem treść Twojego listu.

> 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.

Jeżeli idzie o publikacje akademickie, to w matematyce czy logice
wszyscy publikują w LaTeXu, więc w tym sensie jest całkowicie dzisiejsze.

> Jakie jest podejście współczesne? Ano takie, że piszemy dokument w danym formacie

W jakim formacie?

> i generujemy programem lub skryptem wersję w danym formacie docelowym, np. Html,
Pdf, Doc, Ppt (prezentacje),

Tak się właśnie robi w LaTeXu - piszesz dokument w formacie LaTeX
i generujesz programem lub skryptem wersję w danym formacie docelowym,
zazwyczaj pdf, ps, dvi, czasem html albo rtf.

> 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!

Mnie osobiście najbardziej przypada do gustu texinfo, bo
mogę wygodnie czytać dokumentację w terminalu, gdzie spędzam
większość czasu.

> 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.

Niestety, wolny rynek tak nie działa. Jeżeli tyle pieniędzy od
reklamodawców i czytelników (oraz oczywiście od UE), to nie mają żadnych
dodatkowych obowiązków.

Jak wspominałem, osobiście nie byłem zachwycony magazynem.
Wygląda na to, że nie mają żadnej spójnej koncepcji, i że co miesiąc
publikowane artykuły pochodzą z łapanki.
Co do Twojej krytyki, nie jest tak, że się z nią nie zgadzam,
ale co można zrobić to:
- nawiązać z nimi współpracę
- próbować stworzyć własne czasopismo
- odpuścić sobie

> 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)

Jeśli przyjrzysz się profilom autorów, to z łatwością dostrzeżesz,
że pisze tam wiele osób ze środowisk akademickich albo takich, które
pracują w firmach czy udzielają się w środowiskach scenowych.
(Przynajmniej tak było tych kilka lat temu, kiedy jeszcze mi się
to zdarzało kupować)

> 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!).

Kiedyś jak byłem na wakacjach na Krymie, kupiłem sobie jeden numer
magazynu "haker" (xakep.ru). Niestety, moja zdolność odszyfrowywania
bukw jest raczej ograniczona, ale odniosłem wrażenie, że artykuły były
raczej na wysokim poziomie. Kilka z nich było napisanych przez Krisa
Kaspersky'ego.

> 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).

Z tego co się orientuję, magazyn Programista stanowi medium pomiędzy
autorami a czytelnikami. Podejrzewam, że gdybyś wysłał do nich
rzetelnie napisany artykuł na te tematy, to by go opublikowali.
Znam kilka osób, które tak zrobiły.
(Nb za 3 miesiące ma się ukazać mój felieton w magazynie PSX Extreme)

> 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?

Hmm. "Prawda". Mocne słowo.