1. Opis ogólny
Baza wiedzy Trawers ERP
Zawartość bazy wiedzy
Trudności i dylematy
2. Jak pisać teksty do Bazy wiedzy ?
Baza wiedzy. Słownictwo
Zasady pisania treści (opisów)
Komunikaty i uwagi
Zasady interpunkcji
Przekazywanie opini
Teksty do automatycznego tłumaczenia
SEO Search Engine Optimization
Social Widget
3. Znaczniki. Opis ogólny
4. Znaczniki. Formatowanie treści
4.1 Elementy
4.2 Formatowanie nagłówków
4.3 Odnośniki wewnętrzne
4.4 Odnośniki zewnętrzne
4.5 Grafika. Pliki własne
4.6 Grafika. Linki do stron internetowych
7. Tematy powiązane
1. Opis ogólny
Ogólnie: baza wiedzy, to jest usystematyzowany zbiór informacji, opisów, porad.
Baza Wiedzy. Trawers ERP
Baza wiedzy Trawers ERP
Skomputeryzowany, usystematyzowany zbiór opisów, pojęć, porad, przypadków użycia, itp.
dotyczących programu Trawers. Zawiera informacje skierowane do potencjalnych
i aktualnych użytkowników programu.
Komunikacja w Trawers ERP
Firma Tres CO prowadzi politykę otwartego dostępu do dokumentacji.
Pełna dokumentacja dla wszystkich systemów (modułów) jest dostępna w Bazie wiedzy.
Baza wiedzy jest podstawowym elementem komunikacji między użytkownikami programu
Trawers a działem obsługi serwisowej.
Wspomaga realizację KCS: Knowledge-centered service. Usług zorientowanych na wiedzę.
Komunikacja w dziale serwisowym
Zawartość bazy wiedzy
Baza wiedzy zawiera opisy (artykuły i dokumenty) programu Trawers ERP.
* Opisy rozwiązań funkcjonalnych i technicznych
* Opisy instalowania i aktualizacji
* Opisy wdrażenia i użytkowania
* Opisy administrowania i serwisowania
Trudności i dylematy
Trudności i dylematy (en: Challenges) związane z tworzeniem Bazy wiedzy:
* Zapewnienie wystarczającej ilości czasu aby tworzyć i ciągle aktualizować treści
(artykuły) w Bazie wiedzy w stopniu zapewniającym jej pełną użyteczność.
* Opracowanie stabilnych metod, technik i procesów organizacyjnych, które
zapewniają skuteczne zbieranie informacji i aktualizowanie Bazy wiedzy.
* Rozproszenie wiedzy. Informacje znajdują się w wielu miejscach
i w 'głowach' wielu ludzi. To rodzi trudności.
Trudność w zgromadzeniu tych informacji.
Trudność w ustaleniu, które informacje są aktualne, poprawne i rzetelne.
* Zbudowanie skutecznego systemu samo-pomocy (en: Self-Service), z którego
użytkownik może sam korzystać, bez angażowania pośredników (sprzedawców,
serwisantów, konsultantów).
2. Jak pisać teksty do Bazy wiedzy ?
Podstawowe reguły, wskazówki i sugestie nt. tworzenia opisów programu Trawers.
Baza wiedzy. Słownictwo
Podany komunikat (treść), musi (powinen) być zrozumiały i jednoznaczny
Podstawowym sposobem zagwarantowania tego jest poprawność użytego
zasobu pojęć (słownictwa).
Należy używać konsekwentnie terminologii (pojęć). Nie zmieniać znaczeń.
Unikać używania różnych określeń (nazw) jednego zjawiska lub pojęcia
i jednego określenia (nazwy) dla wielu różnych zjawisk lub pojęć.
Terminologia alfabetycznieSkróty i akronimy
Use terms consistently. Use the one term, one concept rule.
Avoid the use of different terms to convey the same concept,
and avoid the use of one term to convey different concepts.
Zasady pisania treści
* Budować krótkie zdania. Używać znaki interpunkcyjne [.] [,] [;].
W jednym zdaniu zawrzeć tylko jedną myśl, koncepcję, zadanie.
* Używać czasu teraźniejszego. Unikać czasu przeszłego i przyszłego.
Informować o tym, jak jest tu i teraz.
* Wyrazy pisać bez odmian. Pisać w mianowniku liczby pojedyńczej.
Komunikaty, uwagi
* Nie stosować zwrotów: musi, należy, trzeba i podobnych.
Źle:
Należy nacisnąć klawisz, aby wykonać funkcję
Trzeba nacisnąć klawisz, aby wykonać funkcję
Dobrze:
Proszę nacisnąć klawisz, aby wykonać funkcję
* Nie używać agresywnych sformułowań
Źle: Naciśnij klawisz
Dobrze: Proszę nacisnąć klawisz
* Nie używać strony biernej czasowników (en: Passive Voice)
Stosować stronę czynną (en: Active Voice)
Strona czynna ułatwia zrozumienie opisu, gdyż dotyczy osoby wykonującej
czynności, używającej funkcji programu.
Dopuszcza się stosowanie strony biernej w komunikatach błędów.
Aby nie krytykować ani nie upominać personalnie użytkownika.
* Używać zwrotów w trzeciej osobie. Zmniejsza się poziom emocji wymiany informacji.
Źle: Podałeś/aś błędne hasło
Dobrze: Nieprawidłowe hasło lub Hasło jest nieprawidłowe
Źle: Wypełnij PESEL
Dobrze: Proszę wypełnić PESEL
* Nie 'tykać' czytającego.
Wiele tekstów informatycznych powstaje jako bezpośrednie tłumaczenie
treści w języku angielskim. Tam formuła 'ty' (en: You) jest naturalna.
W jezyku polskim (także niemieckim i francuskim) formuła 'ty' jest nieodpowiednia.
Źle: Program Trawers doskonale sprawdzi się w Twojej firmie
Dobrze: Program Trawers będzie przydatny w Państwa firmie
Program Trawers sprawdzi się w Państwa przedsiębiorstwie
Skróty, akronimy
* Skróty tworzyć w konwencji: Snake case, snake_case
Skrót, skrótowiec, akronim (en: Acronym, de: Akronym).
Słowo utworzone przez skrócenie wyrażenia składającego się z dwóch lub więcej słów.
Stosować konwencję: Snake case, snake_case. Tj. konewncję, w której
każda spacja jest zastępowana znakiem podkreślenia (_), a pierwsza litera
każdego słowa jest zapisywana małą literą.
W opisach (dokumentacji) Trawers ERP dopuszczamy wielkie litery,
np. QA2_Transakcje, data_zgłoszenia, stan_realizacji.
Dopuszczamy także konwencję mieszaną: Snake case i Camel case (NormaMin).
np. NormaMin_KIM, NormaMin_KSOM, IloscZlecDoProd.
Zasady interpunkcji
* Unikać stosowania wykrzykników [!] w dokumentacji i komunikatach.
W zasadzie nie ma uzasadnienia stosowanie [!]. Zawsze można zwrócić
uwagę na wybrany element w mniej 'krzykliwy' sposób.
* Nie używać kropek [.] w skrótach.
Źle: Zam. sprzedaży
Dobrze: Zam sprzedaży
Kropki [.] w skrótach są poprawne gramatycznie ale w tekstach na ekranie
są nadmiarowe, niepotrzebnie angażują uwagę.
* Nie nadużywać wielkich liter.
Źle: Faktury Korygujące
Dobrze: Faktury korygujące
Przekazywanie opini
* Nie formułować opinii, że coś jest łatwe lub trudne do zrobienia.
Źle: Na podstawie kroniki, można łatwo zidentyfikować ...
Wg RefNo na dokumencie, można łatwo ...
Arkusze te można łatwo dostosować do wymagań ...
Dobrze: pominąć 'łatwo', prostotę zaakcentować w inny sposób
Jezeli użytkownikowi nie uda się wykonać czynności opisanej jako łatwa
w realizacji, to może spowodować wrażenie, że jest nieudolny
i że nie potrafi pracować z programem.
* Nie stosować egzaltowanych wypowiedzi.
Źle: Przywracanie plików nigdy nie było tak łatwe.
Dobrze: Usprawniono i uproszczono proces przywracania plików.
* Opisywać tylko aktualne właściwości i cechy programu.
Źle: Zestawienie można zapisać w formacie PDF.
Zapisy w innych formatach planuje się w kolejnych wydaniach.
Dobrze: Nie wymieniać przyszłych cech i właściwości.
Teksty do automatycznego tłumaczenia
Tłumaczeniem tekstów w bazie wiedzy zajmują się tłumacze automatyczne,
np. Google Translator.
Patrz niżej: Jak tłumaczyć artykuły Bazy Wiedzy ?
W internecie jest wiele poradników wskazujących jak pisać teksty aby
tłumaczenie było udane.
Niektóre rady:
* Stosować stronę czynną (Active voice) a nie stronę bierną (Passive voice)
Active voice: Use this program to enter vouchers.
Passive voice: This program is used to enter vouchers.
* Używać konsekwentnie terminologii (pojęć). Nie zmieniać znaczeń
Patrz: Słownik pojęć
Słownik pojęć
Use terms consistently. Use the one term, one concept rule:
Avoid the use of different terms to convey the same concept,
and avoid the use of one term to convey different concepts.
* Unikać niestandardowych, nietypowych skrótów i akronimów
Patrz: Skróty i akronimy.
Skróty i akronimy
Use only standard, common abbreviations
* Unikać nadużywania wielkich liter
Use capital letters consistently and appropriately
Patrz też wyżej: Zasady pisania treści
Patrz też:
Wielo-języczność
Jak tłumaczyć artykuły Bazy Wiedzy ?
* Wywołać stronę: https://translate.google.com/
* Ustalić tłumaczenie: z Polski --> na Angielski
* Po lewej stronie: wkleić link z Bazy Wiedzy, np.
fil_trawerswherearedocsdesc.html
* Po prawej stronie: Wywołać strone z tłumaczeniem,
na którą wskazuje link.
Na wybranej stronie jest Baza Wiedzy po angielsku.
Można wybierać kolejne artykuły. Google Translator tłumaczy
arykuły na bieżąco, w locie.
Patrz też wyżej: Zasady pisania treści
SEO Search Engine Optimization
Jak pisać teksty aby wyszukiwarki internetowe je wysoko pozycjonowały ?
Np. Wyrazy pisać bez odmian. Pisać w mianowniku liczby pojedyńczej.
Pisać zdania proste. Nie pisać zdań złożonych. Pisać zdania oznajmujące.
Nie pisać zdań przypuszczających, waunkowych.
Patrz też wyżej: Zasady pisania treści
TODO Szukaj: SEO Search Engine Optimization
Teksty dla ChatGPT
Program ChatGTP wykorzystuje ogólną wiedzę znajdującą się w zasobach
internetowych oraz wiedzę (informacje) obecną w artykułach (tekstach)
na stronach: Baza wiedzy Trawers ERP.
ChatGPT korzysta z rozbudowanej Bazy Wiedzy (ponad 1000 artykułów).
I, dodatkowo, wyszukuje powiązane informacje w zasobach internetu.
CharGPT skutecznie i trafnie formułuje odpowiedzi, gdy dane źródłowe
są odpowiednio przygotowane.
Aktualne i zalecane są wskazówki podane w rozdziale: Zasady pisania treści
Patrz też:
ChatGPT. Pytania i odpowiedzi
Patrz też artykuły z tagiem: #Pomoc-AsystentAI
Social Widget
Social Widget to są ikony (przyciski), które przekazują treści strony www
do mediów społecznościowych (en: Social Media), np. Facebook, Twitter,
Instagram, LinkedIn, YouTube, Pinteres.
Rada: Nie włączać Social Widget do: Baza Wiedzy Trawers ERP.
Nie rozpraszać (nie rozdzielać, nie rozprzestrzeniać) przekazu.
Pozostawić zwarty przekaz. Stosować linki (odsyłacze).
3. Znaczniki. Opis ogólny
W tym dokumencie wymieniono i opisano znaczniki (en: Markup), które
można stosować w tekstach (artykułach) umieszczanych w Bazie Wiedzy.
W Bazie Wiedzy można stosować tylko znaczniki opisane poniżej. Nie można
stosować znaczników HTML. Program tłumaczący nie rozpoznaje znaczników HTML.
Podczas redagowania tekstów znaczniki są widoczne i można je wpisywać i korygować.
Teksty ze znacznikami przekształcane są na wyświetlane treści w 2 formatach:
* Do publikacji w https://trawers.tres.pl w formacie HTML (format graficzny)
Tu znaczniki są zamieniane na elementy graficzne i odnośniki (linki).
* Do przeglądania bezpośrednio w programie: F1-Pomoc (format tekstowy)
Tu znaczniki są pomijane lub zamieniane na tekst.
4. Znaczniki. Formatowanie treści
4.1 Elementy
Znaczniki
---------
* pogrubienie ...
* pogrubienie 1 $B$ ... $/B$
$B$Nie pobierać wielokrotnie tego samego zamówienia$/B$
Nie pobierać wielokrotnie tego samego zamówienia
NOTE: pogrubienie j/w można także uzyskać znacznikami [**] (tak jak ChatGPT)
np. aadd(t_o," tekst zwykły **tekst do pogrubienia** tekst zwykły")
Sekwencja ** musi być poprzedzona spacją
Źle: ---> tekst zwykły**tekst do pogrubienia** tekst zwykły
^
Źle: ---> "**Pogrubienie** zwykły"
^
* pogrubienie 2 ### ...
### Tytuł rozdziału
Tytuł rodziału
* pochylenie $I$ ... $/I$
$I$Nie pobierać wielokrotnie tego samego zamówienia$/I$
Nie pobierać wielokrotnie tego samego zamówienia
* podkreślenie $U$ ... $/U$
$U$Nie pobierać wielokrotnie tego samego zamówienia$/U$
Nie pobierać wielokrotnie tego samego zamówienia
* wyróżnienie 1 $EM$ ... $/EM$
$EM$Nie pobierać wielokrotnie tego samego zamówienia$/EM$
Nie pobierać wielokrotnie tego samego zamówienia
* wyróżnienie 2 $S.n02$ ... $/S$
$S.n02$Nie pobierać wielokrotnie tego samego zamówienia$/S$
Nie pobierać wielokrotnie tego samego zamówienia
* podtutuł $S.c04$ ... $/S$
(patrz formatowanie nagłówków, użycie KLASA)
Przykłady
---------
"$B$ Usługi techniczne $/B$"
Usługi techniczne
"Lista skrócona ($I$ wg kodów pocztowych $/I$)"
Lista skrócona ( wg kodów pocztowych )
"$U$ Specjalizacje podano wg następującej tabeli: $/U$"
Specjalizacje podano wg następującej tabeli:
"$S.c04$Instalowanie i aktualizacje $/S$ "
Instalowanie i aktualizacje
4.2 Formatowanie nagłówków
Znaczniki
---------
$S.KLASA$ ... $/S$
gdzie KLASA jest nazwa klasy stylu CSS zdefiniowanego w:
method GenerujCSS() class TrDokHTML
np. klasa c01:
cHTML += ::html('span.c01 { font-size: 1.2em; font-style: normal; font-weight: bold; color: #CAFEA4; text-decoration: underline; background-color: #457722; padding: 0px;}')
4.3 Odnośniki wewnętrzne
Znaczniki
---------
* nadawanie etykiety: $ID=ETYKIETA$
* odnośnik do etykiety: $A=#ETYKIETA$ ... $/A$
Przykłady
---------
// link do etykiety 01 w dalszej czesci dokumentu
aadd(t_o, " * TechniComm Jarosław Jastrzębowski ")
// Etykieta 01 i formatowanie naglowka wg klasy c01
aadd(t_o, " TechniComm Jarosław Jastrzębowski ")
4.4 Odnośniki zewnętrzne
Znaczniki
---------
* Odnośnik do innego opisu:
$SEE$ TYTUL $ FUNKCJA_FIL $$
Przykłady
---------
" Baza wiedzy. Jak budować ?"
" Partnerzy. Integratorzy"
Odnośnik jest tłumaczony zależnie od formatu, jako:
HTML: link do strony
TXT: -->
Ważne: Opis FUNKCJA_FIL musi znajdować się w drzewie opisów, w tr15_ade
Opisy .html tworzone są tylko na podstawie tego drzewa.
4.5 Grafika. Pliki własne
Np. zrzuty ekranu, fotografie, rysunki, diagramy
Znaczniki
---------
$IMG$ TYTUL $ NAZWA OBRAZKA $
Przykłady
---------
$IMG$ WOE: logowanie $ woe/woe1.png $$
$IMG$ Przewodnik wdrożeniowy $ zest/roadmap.png $$
Obrazki umieścić w katalogu:
* g:\demo\cdtr\dokumentacja\trdok\img\ <-- dla opisów Trawersa
w '\mini' - miniatury obrazków
w '\full' - pełnowymiarowe pokazywane po kliknięciu
4.6 Grafika. Linki do stron internetowych
Np. zrzuty ekranu, fotogrfie, rysunki, diagramy
Linki do obrazków w internecie. Na naszej stronie jest link do obrazka
w internecie. Nie trzeba kopiować obrazków na nasz serwer (prawa autorskie).
Przykład:
$IMG$ Aplikacja webowa $ https://reinvently.com/wp-content/uploads/2019/08/scheme.jpg $$
Przykłady artykułów z obiektami graficznymi:
Wzorce etykiet PrzykładyWzorce dokumentów PrzykładyTrawers. Galeria rysunków
$IMG$ Przewodnik wdrożeniowy $ zest/roadmap.png $$
Obrazki umieścić w katalogu:
* g:\demo\cdtr\dokumentacja\trdok\img\ <-- dla opisów Trawersa
w '\mini' - miniatury obrazków
w '\full' - pełnowymiarowe pokazywane po kliknięciu
Przykłady artykułów z obiektami graficznymi:
Wzorce etykiet Przykłady
Wzorce dokumentów Przykłady
Trawers. Galeria rysunków