Nowy system opinii zostanie docs.microsoft.com

Ten wpis został napisany przez Rob Eisenberg, starszy menedżer programu w zespole docs.microsoft.com.

Misją firmy Microsoft jest umożliwienie każdej osobie i każdej organizacji na świecie osiągnięcia więcej. Było to jedno z naszych zagadnień, ponieważ skompilowaliśmy docs.microsoft.com na otwartej platformie GitHub. Obecnie przechodzimy do następnego poziomu z przejściem do nowego systemu opinii dokumentacji opartej na usłudze GitHub.

Opinie dotyczące zawartości w usłudze GitHub

Chociaż nasza dokumentacja jest od początku używana w usłudze GitHub, nasz mechanizm opinii o zawartości używa usługi Livefyre do komentarzy na temat artykułów. Chociaż Livefyre jest doskonałym rozwiązaniem do komentowania, okazało się niewystarczające do naszych konkretnych potrzeb, czyli śledzenia, przypisywania właścicieli i utrzymania stanu problemów z zawartością zgłaszanych przez klientów.

Zbadaliśmy wiele możliwości, aby to poprawić, ale jedno pytanie, które kierowało dużą częścią naszej pracy, wydawało się ponownie: Gdyby nasza dokumentacja była traktowana tak jak kod open source, co byśmy wykorzystali do rozwiązania tego problemu? Odpowiedź na pytanie wydawała się oczywista: problemy z usługą GitHub, więc zaczęliśmy eksperymentować z integracją interfejsów API usługi GitHub bardziej na naszych stronach dokumentacji, będąc w stanie utworzyć pełny system opinii na podstawie infrastruktury usługi GitHub.

Dzięki nowemu systemowi możesz teraz tworzyć problemy z usługą GitHub bezpośrednio ze strony zawartości, co umożliwia interakcję w znacznie bogatszy sposób z autorami i zespołami produktów. Czy widzisz problem z dokumentem? Przykład nieprawidłowego kodu? Mylące wyjaśnienie? Krytyczne pominięcie? Wystarczy przewinąć do dołu strony i wybrać pozycję Przekaż opinię na temat dokumentacji.

Możesz zobaczyć wszystkie otwarte i zamknięte problemy skojarzone z dokumentem bezpośrednio ze strony dokumentacji — w ten sposób zawsze wiesz, kiedy wszystko zostanie naprawione i rozwiązane:

Możesz komentować, a nawet dodawać reakcje do problemów, które są dla Ciebie ważne:

Teraz pracownicy firmy Microsoft mogą korzystać z pełnej możliwości problemów z usługą GitHub w celu klasyfikacji, reagowania, planowania i rozwiązywania zgłoszonych problemów — a ty zawsze będziesz mieć wgląd w proces.

Przykładowa opinia dotycząca dokumentacji

Załóżmy, że zgłosisz problem z usługą GitHub dla uszkodzonego hiperłącza w artykule. Nasz zespół będzie klasyfikować problem, przypisywać etykietę i przypisywać właściciela, aby wprowadzić poprawkę (lub zadawać pytania. Gdy właściciel prześle żądanie ściągnięcia, które rozwiąże ten problem, otrzymasz powiadomienie (na podstawie ustawień powiadomień usługi GitHub), że problem został rozwiązany/zamknięty, tworząc pozytywny cykl opinii.

Ponadto możesz wykorzystać całą standardową dobroć usługi GitHub, taką jak Markdown w komentarzach, subskrypcjach do poszczególnych problemów lub całych repozytoriów, kanałów informacyjnych RSS działań organizacji, @ wzmianki, przypisy i nie tylko! Uważamy, że głębszy poziom integracji narzędzi open source będzie wspierać nowe możliwości rozwoju społeczności i współpracy.

Separacja opinii o produkcie

Jednym z problemów z poprzednim systemem było połączenie opinii między produktem a dokumentacją w jednym strumieniu — bardzo trudno było sklasyfikować i wykonać kolejne czynności, gdy nie wszystkie elementy są spójnie oznaczone etykietami. Zrobiliśmy krok naprzód, aby rozwiązać ten problem, tworząc jasny sposób oddzielenia tych dwóch:

Klikając Przekaż opinię o produkcie, nastąpi przekierowanie bezpośrednio do witryny, w której zespół produktu skojarzony z określoną stroną dokumentacji obsługuje opinie o produkcie.

Roll-Out

Być może zastanawiasz się, kiedy system opinii będzie na żywo. Od kilku miesięcy przeprowadzamy go pilotażowo dla środowiska IDE programu Visual Studio oraz dokumentacji interfejsu wiersza polecenia platformy Azure . Począwszy od połowy lutego, zaczniemy to wprowadzać we wszystkich docs.microsoft.com.

Twoja opinia

Twoja opinia jest dla nas ważna, więc chcemy szybko wprowadzić ten nowy system w twoje ręce. Chociaż jest to nasz kolejny krok w ulepszaniu opinii i zaangażowania na naszej platformie, nie jest to w żaden sposób nasz ostatni krok. Pamiętaj, aby wyrazić swoje przemyślenia dotyczące zmian w witrynie GitHublub oznacz nas w serwisie Twitter.