Pisanie artykułów dla bazy wiedzy

Jest wiele elementów, które trzeba wziąć pod uwagę przy pisaniu i edycji artykułu. Chcesz, aby jednocześnie twój artykuł był kompletny, zwięzły, rzeczowy? Napisanie takiego artykułu na pewno nie jest najprostszą rzeczą na świecie. Oto kilka wskazówek, które ułatwią napisanie artykułu. Pamiętaj, że jest to wiki i zawsze możemy coś skorygować, jeśli uznamy, że nie jest właściwe.

Pisz artykuły skierowane do wszystkich

Chcielibyśmy, aby Pomoc dla Firefoksa była użyteczna dla wszystkich użytkowników Firefoksa. Oznacza to, że artykuły powinny być pisane językiem zrozumiałym dla wszystkich, a nie tylko dla osób obeznanych z techniką i terminologią komputerową. Artykuł powinien opierać się na założeniu, że użytkownik nie zmienił żadnych domyślnych ustawień systemu operacyjnego i Firefoksa. Drugim ważnym założeniem, które należy przyjąć, to że artykuł jest skierowany do osób, które bez dokładnej instrukcji krok po kroku nie wiedzą, jak, np. zmienić ustawienia lub dodać przycisk do paska narzędzi.

Nadaj dobry tytuł

Tytuł artykułu wraz z jego opisem dla wyników wyszukiwania to podstawowe elementy, jakie mają wpływ na ocenę przydatności artykułu do rozwiązania problemu, z jakim może borykać się użytkownik. Nazywamy to „zaufaniem użytkowników” i to bezpośrednio wpływa na popularność artykułu. Nawet jeśli artykuł jest wyświetlany na górze wyników wyszukiwania, to użytkownik musi być przekonany, że jego zawartość odpowiada zapytaniu określonemu podczas wyszukiwania, by kliknąć odnośnik do artykułu i zapoznać się z jego treścią.

Tytuł artykułu powinien sugerować, co znajduje się w artykule. Najważniejsze są pierwsze słowa tytułu – powinny być możliwie jak najbardziej zrozumiałe i pasować do słów kluczowych. Pozwoli to użytkownikom szybko rozpoznać, co się w artykule znajduje. Ponadto tytuł powinien spełniać następujące zalecenia:

• długość tytułu – na stronie wyników wyszukiwania Google jest wyświetlane maksymalnie 70 znaków; tytuł artykułu – jeśli jest to niezbędne – może być dłuższy, ale podane słowa kluczowe powinny znajdować się wśród tych 70 znaków,
• nie należy używać tych samych słów i zwrotów w tytułach wielu artykułów,
• nie należy używać czasowników w formie trwającej.
• nie należy używać dwukropka w tytule artykułu, ponieważ uniemożliwia tworzenie odnośnika do tego artykułu (błąd 749835).

Pamiętaj, że całe wyjaśnienie nie musi być zawarte w tytule. Można w krótkim opisie przekazać użytkownikowi dodatkowe informacje o tym, co znajduje się w artykule.

Sprawdź ciąg słów

Podczas nadawania tytułu, SUMO automatycznie tworzy ciąg słów – elementy wyświetlane na końcu adresu URL artykułu. Ciąg słów jest ograniczony do 50 znaków; spacje są przetwarzane jako myślniki. Ciąg słów powinien być spójny z tytułem, ale ze względu na ograniczenie liczby znaków nie musi być taki sam. Pamiętaj, aby sprawdzić końcówkę automatycznie generowanego ciągu. Czasami słowo jest ucięte lub kończy się kreską. Takie przypadki należy poprawić.

Kategorie, produkty i tematy

W przeważającej większości artykuły są przypisane do kategorii jak to zrobić lub rozwiązywanie problemów. Czasami piszemy artykuły, takie jak ten, które należą do kategorii jak wesprzeć, a czasami do jeszcze innej kategorii.

Czasami „artykuły dotyczą” kilku produktów. Artykuły te należą do jednego głównego „tematu” i opcjonalnie do „sub-tematu”.

Słowa kluczowe

Słowa kluczowe usprawniają wyszukiwanie w SUMO. Należy je wprowadzać w polu słów kluczowych, ale powinny być używane w szczególnych okolicznościach, ponieważ niewłaściwie podane słowo kluczowe może negatywnie wpływać na wyniki wyszukiwania. My rzadko używamy słów kluczowych. Więcej informacji na ten temat znajduje się w artykule: When and how to use keywords to improve an article's search ranking.

Dobry opis dla wyników wyszukiwania

Opis dla wyników wyszukiwania razem z tytułem artykułu, to podstawowe elementy, jakie mają wpływ na ocenę przydatności artykułu do rozwiązania problemu, z jakim może borykać się użytkownik. Nazywamy to „zaufaniem użytkowników” i to bezpośrednio wpływa popularność artykułu. Nawet jeśli artykuł jest wyświetlany na górze wyników wyszukiwania, to użytkownik musi być przekonany, że jego zawartość odpowiada zapytaniu określonemu podczas wyszukiwania, by kliknąć odnośnik do artykułu i zapoznać się z jego treścią.

Opis dla wyników wyszukiwania dla artykułów kategorii jak to zrobić powinien zawierać tematy poruszone w artykule, dla artykułów kategorii rozwiązywanie problemów – występujące objawy. Ponadto powinien spełniać następujące zalecenia:

• powinien być krótki i na temat – pamiętasz ogłoszenia drobne? napisz właśnie w takim stylu, wyszukiwarki obcinają wszystko powyżej 160 znaków,
• nie powinien zawierać znaczników wiki,
• nie należy często używać określenia „W tym artykule opisano”, zamiast tego zwrotu można rozważyć użycie:
  • Pokażemy ci,
  • Wyjaśnimy,
  • Na tej stronie wyjaśniono,
  • Ten artykuł objaśnia,
  • Przedstawiamy.

Pisz z zaangażowaniem

Pomoc dla Firefoksa to repozytorium informacji technicznych na temat działania przeglądarki internetowej Firefox. Dokumentacja zawiera wykaz różnych funkcji Firefoksa, procedur rozwiązywania problemów oraz instrukcje rozwiązywania wspólnych problemów. Jest dostępna za pomocą funkcji wyszukiwania na każdej stronie lub ciśnij komputerem w przeciwległy róg pokoju, gdzie jednorożce za pomocą swej tęczowej mocy zamienią go w cukierek po zjedzeniu, którego osiągniesz 70 poziom komputerowego ninji.

Nie śpisz? To dobrze.

Ten akapit brzmi jak nudny wykład, przynajmniej do momentu, gdy pojawiły się jednorożce. Humor i emocje (NIESPODZIANKA!) to tylko niektóre z technik, których możemy użyć, aby zaangażować ludzi. Opisane poniżej techniki mają za zadanie pobudzenie twojego umysłu poprzez zrelaksowanie i zwrócenie uwagi na ważne elementy. Dzięki temu przekazywane informacje są łatwiejsze do zrozumienia i zapamiętania.

• Konwersacyjny styl pisania – używaj niesformalizowanego, aktywnego stylu podobnego do rozmowy z drugą osobą.
• Humor i emocje – użycie humoru jest dobre, ale czasami trudne lub wręcz nie możliwe do przetłumaczenia na inne języki. Emocje, takie jak niespodzianka i np. „Nie wiedziałem, że!” (nie mam pewności, co wywołuje ta emocja) mogą być łatwiejsze do dołączenia do tekstu.
• Różne style uczenia się – tak jak w szkole, ludzie uczą się w różny sposób, ponadto każdy czerpie korzyści widząc tę samą treść wyrażoną na wiele sposobów.
• Powtórzenia – jeśli coś wyjaśnisz różnymi sposobami, korzystając z różnych mediów, stanowi to formę powtórzenia, co jest doskonałym sposobem na zapamiętanie przez ludzi tego, co jest najważniejsze.
• Obrazki i filmy – użycie do wyjaśnienia obrazków i filmów razem z tekstem jest nie tylko kolejnym wspaniałym sposobem pomocy – jest prostym sposobem użycia wielu stylów nauki i powtórek.
• Aktywność – szczególnie w instrukcji jest dobrze dać coś ludziom do wykonania. Z jednej strony jest dobrze przeczytać instrukcje i zrozumieć proces, ale często zaangażowanie w wykonanie pewnych czynności daje jeszcze lepsze rezultaty.

Artykuł Jak ustawić stronę startową jest dobrym przykładem użycia tych technik.

Dobry wstęp

Wraz z tytułem i spisem treści, wstęp jest tym, co umożliwia ludziom szybkie określenie czy są we właściwym miejscu.

• W instrukcji, czy artykule typu „jak to zrobić” podaj krótki opis tego, co można się nauczyć.
• W artykule referencyjnym podaj krótkie objaśnienie funkcji.
• W artykule typu „rozwiązywanie problemów” podaj krótki opis problemu i objawów.

Dobry wstęp zazwyczaj może być dobrym tekstem dla opisu dla wyników wyszukiwania. Wystarczy go skopiować i wkleić w polu „Opis dla wyników wyszukiwania”.

Twórz artykuły efektywnie

Ogólną zasadą jest tworzenie umiejętności, począwszy od prostych do złożonych, starając się zachować potrzebne większości ludzi informacje na pierwszym planie. Tak więc proste, ogólne rozwiązania będą zazwyczaj miały priorytet przed rozwiązaniami złożonymi lub przypadkami skrajnymi.

Twórz opisowe nagłówki

Nasze artykuły są często obszerne, zatem bardzo ważnym, by ułatwić znalezienie potrzebnej części artykułu, jest stosowanie opisowych nagłówków. Spójrz na spis treści swojego artykułu i sprawdź czy działa i daje przegląd jego zawartości.

Twórz instrukcje łatwe do wykonania

Najważniejsze, aby podczas pisania instrukcji pamiętać o objęciu przez instrukcję wszystkich działań niezbędnych do wykonania zadania. Jeśli na przykład po wybraniu preferencji trzeba nacisnąć przycisk OK, aby przejść do następnego kroku, sprawdź czy w ramach tego kroku jest zawarta instrukcja naciśnięcia tego przycisku. Należy wziąć pod uwagę następujące dodatkowe zagadnienia:

• zazwyczaj jest wiele sposobów osiągnięcia końcowego rezultatu – staraj się zawsze wskazać sposób najbardziej przyjazny użytkownikowi, używając, gdy jest to możliwe, menu i interfejsów graficznych,
• używaj pełnych zdań, opisując jak uzyskać dostęp do interfejsu użytkownika,
• w instrukcjach dołączaj opis oczekiwanych rezultatów, np. Po naciśnięciu przycisku OK okno zostanie zamknięte.

Oto przykład z artykułu: Jak ustawić stronę startową z objaśnieniami w nawiasach.

Ustawienie jednej witryny jako strony startowej
(Nagłówek, a poniżej instrukcje do wykonania)

Jeśli lubisz prostotę, znajdziesz tu opis, jak ustawić stronę startową w trzech krokach.
(Treść instrukcji z dołączoną grafiką ilustrująca czynności do wykonania)

1. Przejdź do strony, którą chcesz ustawić jako stronę startową. Jeśli chcesz ustawić pustą stronę startową, otwórz nową kartę.
2. Kliknij ikonę po lewej stronie adresu witryny i przeciągnij ją na przycisk przedstawiający dom, znajdujący się na pasku narzędzi.
3. Naciśnij Tak, by potwierdzić.

Wypróbuj: Naciśnij przycisk strony startowej i nowa strona startowa zostanie otworzona w aktywnej karcie. Nie ma nic łatwiejszego!
(Aktywność – daje czytelnikowi zadanie i opisuje oczekiwany wynik)

Krótkie odnośniki – opcjonalne

Na dole artykułu znajduje się szablon do dodawania skróconego odnośnika mzl.la. Jest on głównie używany dla ułatwienia dołączania odnośników do artykułów w postach na Twitterze.

Jeśli zdecydujesz się dodać do artykułu taki szablon, przed wykonaniem skrótu i jego zamieszczeniem sprawdź czy spełnia on wymagania. Adres URL artykułu nie może zawierać określenia lokalizacji ani dodatkowych elementów na końcu adresu.

Na przykład, gdy jest wyświetlany artykuł: Aktualizacja Firefoksa, w pasku adresu przeglądarki, w zależności od używanego systemu operacyjnego i wersji przeglądarki, może być widoczny następujący adres:

https://support.mozilla.org/pl/kb/Aktualizacja%20Firefoksa#os=win7&browser=fx22

Przed utworzeniem skróconego odnośnika trzeba go zmienić do następującej postaci:

https://support.mozilla.org/kb/Aktualizacja%20Firefoksa

Jak widać, został usunięty element wskazujący na konkretną lokalizację (w tym przypadku /pl) oraz elementy znajdujące się na końcu adresu wskazujące na system operacyjny i wersję programu (#os=win7&browser=fx22). Dopiero taka postać adresu URL nadaje się do utworzenia krótkiego odnośnika.

Tworzenie krótkiego odnośnika.

1. Przejdź na witrynę https://bitly.com.
2. W polu Paste a link to shorten it wklej przygotowany wg wcześniejszego opisu adres URL.
3. Naciśnij przycisk Shorten. Zostanie wyświetlona nowa strona z gotowym do skopiowania skróconym odnośnikiem.
4. Naciśnij przycisk Copy, by skopiować odnośnik.
5. Wróć do tworzonego artykułu i wklej skopiowany odnośnik do szablonu.

Informacje o stylu SUMO

Jak już wcześniej informowaliśmy, do pisania artykułów do bazy wiedzy powinien być używany bezpośredni, konwersacyjny styl. Tworząc artykuł w języku angielskim, należy unikać sformułowań w stylu: "If a user's bookmarks have been lost...", zamiast tego proponujemy użyć: "If you've lost your bookmarks...". Tworząc artykuł w języku polskim trzeba wziąć pod uwagę wymagania polskiej gramatyki, składni i uwarunkowania kulturowe. Powyższy przykład w języku polskim brzmiałby nienaturalnie i nie spełniałby wymogów języka polskiego, gdzie trzeba zwracać uwagę na zwracanie się do obojga płci. W języku polskim najlepiej brzmiałby zwrot „Jeśli użytkownik stracił swoje zakładki…” bądź alternatywnie, uwzględniając zwracanie się do obu płci, „Jeśli straciłeś/straciłaś swoje zakładki” Poniżej inne typowe problemy stylistyczne, jakie mogą zdarzyć podczas pisania artykułów pomocy.

Zawsze stosuj zwroty i terminy, tak jak są wyświetlane w interfejsie Firefoksa. Miej na uwadze następujące zagadnienia:

• nazwy wtyczek nie zawierają łącznika,
• nazwy dodatków mogą zawierać łącznik,
• strona domowa zawsze składa się z dwóch słów.

Terminy komputerowe

• Internet piszemy dużą literą.
• Website – witryna to jedno słowo.
• Log in i log out (zaloguj i wyloguj} to czasowniki. Przykład: "Log in to the website." (Zaloguj się na witrynie).
• Login i logout to rzeczowniki (zazwyczaj używane w formie przymiotnikowej). Przykład: "Click the login button." W języku polskim jest używana forma „Naciśnij przycisk logowania”.
• Używaj „email” zamiast „e-mail”. W języku polskim jest na odwrót – należy używać „e-mail”.
• Forma mnoga od CD-ROM to CD-ROMs. W języku polskim CD-ROM-y.

Odnośniki do stron mozilla.org należy formować, tak aby mogły być rozpoznawane przez zlokalizowane strony.

• Należy używać http://www.mozilla.org/firefox zamiast http://www.mozilla.org/en-US/firefox. Taki zapis umożliwia wyświetlanie stron mozilla.org w języku używanym przez przeglądarkę za pomocą, której użytkownik łączy się ze stronami mozilla.org.

Pisz dużą literą następujące elementy:

• nazwy własne,
• pierwsze słowo zdania,
• skróty i akronimy, chyba że normalnie są pisane małą literą,
• pierwsze słowo w listach punktowanych i numerowanych (dotyczy języka angielskiego),
• nazwy klawiszy na klawiaturze,
• pierwsze słowo zdania po dwukropku (dotyczy języka angielskiego),
• pierwsze słowo nagłówka lub tytułu.

Sposób pisania w listach punktowanych i numerowanych w języku polskim przedstawia powyższa lista.

Dla jasności, nie używaj i.e. i e.g. (dotyczy języka angielskiego).

Dla wielu elementów można stosować specjalne style wizualne osiągane poprzez zawarcie elementu w odpowiednim znaczniku. Wykaz tych znaczników wraz z przykładami znajduje się w artykule: Markup cheat sheet.

Istnieją też specjalne znaczniki wiki – {for} – umożliwiające ukierunkowanie informacji do konkretnej wersji Firefoksa lub systemu operacyjnego. Dzięki temu w tym samym artykule można jedne informacje skierować do użytkowników systemu Windows, a inne do użytkowników systemu Mac OS X i będą one wyświetlane tylko w danym systemie operacyjnym. Jest to bardzo przydatne przy tworzeniu zestawu instrukcji, ponieważ różne systemy mają różne nazwy funkcji i ich rozmieszczenie w interfejsie. Więcej szczegółów na ten temat znajduje się w artykule: How to use "For" tags.