Pisanie techniczne dla programistów

HTML, CSS, JavaScript, Python, PHP, C++, Dart — istnieje tak wiele języków programowania, że ​​możesz nawet w pełni biegle posługiwać się kilkoma z nich! Ale ponieważ dążymy do pisania coraz lepszego kodu, sposób, w jaki piszemy i komunikujemy się w języku potocznym, staje się coraz ważniejszy… a może nawet pomijany.

Sposób, w jaki piszemy o kodzie i wokół niego, jest prawdopodobnie równie ważny jak sam kod. I niezależnie od tego, gdzie znajdujesz się na tej linii, wszyscy możemy się zgodzić, że nasze słowa mogą zarówno pomóc, jak i zaszkodzić efektywności kodu.

W tym artykule chcę opisać, w jaki sposób te dwie pozornie różne dziedziny — programowanie i pisanie — mogą się połączyć i przenieść nasze umiejętności programistyczne na wyższy poziom.

Czekaj, pisanie techniczne? Tak, dokładnie to mam na myśli. Naprawdę wierzę, że wszyscy jesteśmy pisarzami w takim czy innym sensie. I jestem tutaj, aby dać ci elementarz z poradami i przykładami dotyczącymi pisania, jak może sprawić, że będziesz lepszym programistą i komunikatorem.

Pisanie techniczne jest wszędzie

W zeszłym roku zespół odpowiedzialny za popularnego klienta Mac Git, Tower, ankietowanych ponad 4,000 programistów i odkryli, że prawie 50% z nich spędzało od 3 do 6 godzin dziennie na pisaniu kodu.

I tak, to jedno badanie ankietowe dość niszowej grupy, ale wyobrażam sobie, że wielu z nas mieści się gdzieś w tym zakresie. W każdym razie programista nie pisze kodu 24 godziny na dobę, 7 dni w tygodniu, ponieważ jak sugeruje ta ankieta, spędzamy mnóstwo czasu na robieniu innych rzeczy.

Może to obejmować:

• zademonstrowanie nowej funkcji,
• udokumentowanie tej nowej funkcji,
• aktualizowanie biletu służbowego związanego z tą nową funkcją lub
• zaległości działają w celu obsługi tej nowej funkcji.

Oczywiście zawsze jest czas na przerwy w łazience i Wordle.

W każdym razie większość rzeczy, które zwykle robimy, obejmuje komunikację z ludźmi, takimi jak Twój zespół, współpracownicy, klienci, użytkownicy i inni programiści.

Więc spędzamy sporą część naszego czasu komunikując się z ludźmi poprzez słowa oprócz komunikacji, którą mamy z komputerami za pośrednictwem kod. Słowa są językiem pisanym. A gdybyśmy lepiej pisali nasze słowa, lepiej byśmy się porozumiewali. Kiedy lepiej się komunikujemy, jest bardziej prawdopodobne, że dostaniemy to, czego chcemy.

To jest pisanie techniczne 101.

I to się nawet nie kończy. Niektórzy programiści lubią też tworzyć własne produkty, co oznacza, że ​​marketing musi być częścią ich pracy. Pisanie techniczne również odgrywa w tym ogromną rolę. Więc tak. Myślę, że całkiem uczciwie jest powiedzieć, że pisanie techniczne jest rzeczywiście wszędzie.

Czym jest dobra gramatyka?

Przy tak wielu językach programowania, ostatnią rzeczą, jakiej chcemy, jest nauczenie się innego.

Gramatyka jest integralną częścią języka angielskiego i odblokowuje pełen potencjał komunikacji. Czyni nas bardziej formalnymi, profesjonalnymi i spójnymi.

Pozwól, że przedstawię ci krótkie podsumowanie języka.

Składnia angielska

Podobnie jak języki programowania, angielski ma dobrze zdefiniowaną składnię i zaczyna się od słów.

Słowa są budulcem języka angielskiego i mieszczą się w ośmiu wiadrach:

Pomyśl o takich jak UI komponenty: są to elementy modułowe, po których można się poruszać, aby zbudować kompletne i solidne zdanie, w taki sam sposób, w jaki można złożyć kompletne i solidne zdanie UI. Czy wszystkie elementy muszą być dostępne przez cały czas? Zdecydowanie nie! Połącz zdanie z kawałków, których potrzebujesz, aby dopełnić doświadczenie, tak jak w przypadku interfejsu.

Głos i ton

Słownictwo, interpunkcja, struktura zdania i dobór słów. To są wszystkie składniki języka angielskiego. Używamy ich do dzielenia się pomysłami, komunikowania się z naszymi przyjaciółmi i rodziną oraz wysyłania e-maili do naszych współpracowników.

Ale ważne jest, aby wziąć pod uwagę dźwięk naszych wiadomości. To niesamowite, jak jeden wykrzyknik może całkowicie zmienić ton wiadomości:

1. Lubię programować.
2. I lubić programowanie! :)

Łatwo pomylić głos z tonem i na odwrót.

Głos dotyczy naszego doboru słów, który zależy od kontekstu. Na przykład samouczek dla początkujących częściej używa slangu i języka nieformalnego, aby przekazać przyjazny głos, podczas gdy dokumentacja może być napisana w sposób formalny, poważny i profesjonalny, aby od razu przejść do sedna.

Ta sama wiadomość, napisana dwoma różnymi głosami:

• Zabawa: „Rozwiń swoją sieć społecznościową i bądź na bieżąco z trendami”.
• Poważny: „Znajdź pracę w jednej z największych aplikacji społecznościowych i rynku pracy online”.

Nie jest niczym niezwykłym przypadkowe napisanie wiadomości, które wydają się protekcjonalne, obraźliwe i nieprofesjonalne. To jest gdzie ton wchodzi w grę. Czytaj swoje wiadomości na głos, poproś inne osoby o przeczytanie ich za Ciebie i poeksperymentuj z interpunkcją i strukturą zdania. W ten sposób szlifujesz swój ton.

Oto inny sposób myślenia: Twój głos nigdy się nie zmienia, ale zmienia się ton. Twój głos jest podobny do tego, kim jesteś jako osoba, podczas gdy ton to sposób, w jaki reagujesz w danej sytuacji.

Głos czynny i bierny

Zdanie zawsze zawiera aktora, czasownik i cel. Kolejność, w jakiej one przychodzą, określa, czy zdanie jest napisane głosem czynnym, czy biernym.

Aktor jest na pierwszym miejscu aktywny głos. Na przykład: „CSS maluje tło”.

Zdania używające głosu aktywnego są prostsze niż ich odpowiedniki. Są wyraźniejsze, krótsze i bardziej zrozumiałe — idealne dla bardziej profesjonalnego głosu, który przechodzi od razu do sedna.

z Strona bierna, aktor jest ostatni. (Widzisz, co tam zrobiłem?) Oznacza to, że nasz aktor – w tym przypadku CSS – kończy się tak: „Tło jest namalowane przez CSS”.

Czytelnicy zwykle konwertują w głowach głos bierny na głos aktywny, co skutkuje dłuższym czasem przetwarzania. Jeśli kiedykolwiek słyszałeś, że pisanie aktywnym głosem jest lepsze, to zazwyczaj jest to powód. Pisarze technologiczni przez większość czasu wolą głos aktywny, z nielicznymi wyjątkami, takimi jak cytowanie badań: „Sugerowano, że…”

Ale to nie znaczy, że zawsze powinieneś dążyć do aktywnego głosu. Przełączanie się z jednego do drugiego — nawet w tym samym akapicie — może sprawić, że treść będzie płynniej przechodzić od jednego zdania do drugiego, jeśli zostanie efektywnie wykorzystana.

Unikanie błędów

W gramatyce chodzi o strukturę i poprawność języka, a nie ma nic lepszego do osiągnięcia tego niż szybka korekta dokumentu. Bardzo ważne jest, aby pozbyć się błędów ortograficznych, problemów gramatycznych i niedoskonałości semantycznych.

Na końcu tego artykułu pokażę Ci nieocenione narzędzia, z których korzystają profesjonaliści, aby uniknąć błędów w pisaniu. Oczywiście w dzisiejszych czasach prawie we wszystkim są wbudowane moduły sprawdzania pisowni; nasze edytory kodu mają nawet wtyczki do sprawdzania pisowni i lintingu, które pomagają zapobiegać błędom. 

Ale jeśli szukasz kompleksowego narzędzia do wszechstronnej gramatyki, Grammarly to jedno z najczęściej używanych narzędzi. Nie dostanę za to ani nic. To naprawdę świetne narzędzie, którego wielu redaktorów i pisarzy używa do pisania czystej i przejrzystej treści — podobne do tego, jak można użyć Emmeta, eslinta lub innego lintera do pisania czystego i jasnego kodu.

Pisanie komentarzy do kodu

To, co piszemy dla innych programistów, może mieć duży wpływ na ogólną jakość naszej pracy, niezależnie od tego, czy chodzi o to, co piszemy w kodzie, jak wyjaśniamy kod, czy też udzielamy opinii na temat fragmentu kodu.

Interesujące jest to, że każdy język programowania ma standardowy zestaw funkcji do pisania komentarza. Powinni wyjaśnić, co robi kod. Nie mam przez to na myśli niejasnych komentarzy takich jak:

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Zamiast tego użyj komentarzy, które zawierają więcej informacji:

red *= 1.2 // Apply a 'reddish' effect to the image

Wszystko zależy od kontekstu. „Jaki program buduję?” jest dokładnie tym rodzajem pytania, które powinieneś sobie zadać.

Komentarze powinny stanowić wartość dodaną

Zanim przyjrzymy się, co składa się na „dobry” komentarz w kodzie, oto dwa przykłady leniwych komentarzy:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

Pamiętaj, że celem komentarza jest dodanie wartości do fragmentu kodu, a nie jego powtórzenie. Jeśli nie możesz tego zrobić, lepiej zostaw kod bez zmian. To, co sprawia, że ​​te przykłady są „leniwe”, to jedynie ponowne przedstawienie tego, co w oczywisty sposób robi kod. W tym przypadku komentarze są zbędne, ponieważ mówią nam to, co już wiemy — nie dodają wartości!

Komentarze powinny odzwierciedlać aktualny kod

Nieaktualne komentarze nie są rzadkością w dużych projektach; ośmielę się powiedzieć w większość projektów.

Wyobraźmy sobie Davida, programistę i świetnego faceta, z którym można się spotykać. David chce posortować listę łańcuchów alfabetycznie od A do Z, więc robi to, co oczywiste w JavaScript:

cities = sortWords(cities) // sort cities from A to Z

David uświadamia sobie, że sortWords() faktycznie sortuje listy od Z do A. To nie jest problem, ponieważ może po prostu odwrócić wynik:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

Niestety David nie zaktualizował swojego komentarza do kodu.

Teraz wyobraź sobie, że nie opowiedziałem ci tej historii, a wszystko, co widziałeś, to powyższy kod. Można by pomyśleć, że po uruchomieniu drugiej linii kodu `miasta` zostaną posortowane od Z do A! Całe to fiasko zamieszania było spowodowane nieaktualnym komentarzem.

Chociaż może to być przesadzony przykład, coś podobnego może (i często się zdarza) zdarzyć, jeśli ścigasz się z krótkim terminem. Na szczęście można temu zapobiec, przestrzegając jednej prostej zasady… zmieniaj swoje komentarze w tym samym czasie, kiedy zmieniasz kod.

To jedna prosta zasada, która uchroni Ciebie i Twój zespół przed wieloma dług techniczny.

Teraz, gdy wiemy, jak wyglądają źle napisane komentarze, spójrzmy na kilka dobrych przykładów.

Komentarze powinny wyjaśniać kod unidiomatyczny

Czasami naturalny sposób robienia rzeczy nie jest właściwy. Programiści być może będą musieli nieco „złamać” standardy, ale kiedy to zrobią, warto zostawić mały komentarz wyjaśniający ich uzasadnienie:

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

To pomocne, prawda? Jeśli byłeś odpowiedzialny za sprawdzenie tego kodu, mogłeś ulec pokusie poprawienia go bez komentarza wyjaśniającego, co się dzieje.

Komentarze mogą identyfikować przyszłe zadania

Inną przydatną rzeczą do zrobienia z komentarzami jest przyznanie, że jest jeszcze więcej pracy do wykonania.

// TODO: use a more efficient algorithm
linearSort(ids)

W ten sposób możesz skupić się na swoim przepływie. A w późniejszym terminie Ty (lub ktoś inny) możesz wrócić i to naprawić.

Komentarze mogą odsyłać do źródła

Właśnie znalazłeś rozwiązanie swojego problemu na StackOverflow. Po skopiowaniu i wklejeniu tego kodu czasami dobrze jest zachować link do odpowiedzi, która Ci pomogła, aby móc do niej wrócić w przyszłości.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

To ważne, ponieważ rozwiązania mogą się zmieniać. Zawsze dobrze jest wiedzieć, skąd pochodzi Twój kod, na wypadek gdyby kiedykolwiek się zepsuł.

Pisanie pull requestów

Wyciągnij żądania (PRs) są podstawowym aspektem każdego projektu. Siedzą w samym sercu recenzji kodu. A przeglądy kodu mogą szybko stać się wąskim gardłem w wydajności Twojego zespołu bez dobrego sformułowania.

Dobro PR opis podsumowuje co dokonywana jest zmiana i dlaczego to się robi. Duże projekty mają szablon pull request, taki jak ten zaadaptowany z prawdziwy przykład:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Unikaj niejasnych PR tytuły

Unikaj tytułów, które wyglądają tak:

• Napraw kompilację.
• Naprawić błąd.
• Dodaj łatkę.

Te nawet nie próba aby opisać, z jaką kompilacją, błędem lub łatką mamy do czynienia. Trochę dodatkowych szczegółów na temat tego, która część kompilacji została naprawiona, który błąd został usunięty lub jaka została dodana łatka, może znacznie pomóc w nawiązaniu lepszej komunikacji i współpracy z kolegami. Ustawia poziomy i sprawia, że ​​ludzie są na tej samej stronie.

PR tytuły są tradycyjnie pisane w języku czas imperatywny. Stanowią jednowierszowe podsumowanie całości PRi powinni opisać co jest robione przez PR.

Oto kilka dobrych przykładów:

• Obsługa niestandardowych atrybutów srcset w NgOptimizedImage
• Domyślna konfiguracja obrazu do 75% jakości obrazu
• Dodaj jawne selektory dla wszystkich wbudowanych ControlValueAccessor

Unikaj długich PRs

Duża PR oznacza obszerny opis i nikt nie chce przeglądać setek lub tysięcy wierszy kodu, czasami po prostu odrzucając całość!

Zamiast tego możesz:

• komunikować się ze swoim zespołem poprzez Zagadnienia,
• zrobić plan,
• rozbić problem na mniejsze kawałki lub
• pracuj na każdym kawałku osobno z własnym PR.

Czy nie jest teraz dużo czyściej?

Podaj szczegóły w PR ciało

w przeciwieństwie do PR tytuł, ciało jest dotychczasowy miejsce na wszystkie szczegóły, w tym:

• Dlaczego jest PR skończone?
• Dlaczego to najlepsze podejście?
• Wszelkie niedociągnięcia w podejściu i pomysły na ich rozwiązanie w miarę możliwości
• Numer błędu lub zgłoszenia, wyniki testów itp.

Zgłaszanie błędów

Raporty o błędach są jednym z najważniejszych aspektów każdego projektu. A wszystkie świetne projekty opierają się na opiniach użytkowników. Zwykle, nawet po niezliczonych testach, to właśnie użytkownicy znajdują najwięcej błędów. Użytkownicy są również wielkimi idealistami i czasami mają pomysły na funkcje; proszę ich posłuchaj!

W przypadku projektów technicznych wszystko to odbywa się poprzez zgłaszanie problemów. Inny programista może łatwo znaleźć i odpowiedzieć na dobrze napisane wydanie.

Na przykład większość dużych projektów jest dostarczana z szablon:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Zbierz zrzuty ekranu

Uchwyć problem za pomocą narzędzie do zrzutów ekranu systemu.

Jeśli to zrzut ekranu CLI programu, upewnij się, że tekst jest wyraźny. Jeśli to UI programu, upewnij się, że zrzut ekranu zawiera właściwe elementy i stany.

Może być konieczne zarejestrowanie rzeczywistej interakcji, aby zademonstrować problem. Jeśli tak jest, spróbuj nagrywaj GIF-y za pomocą narzędzia do nagrywania ekranu.

Jak odtworzyć problem

Programistom znacznie łatwiej jest rozwiązać błąd, gdy jest on obecny na ich komputerze. Dlatego dobre zatwierdzenie powinno zawierać kroki w celu dokładnego odtworzenia problemu.

Oto przykład:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Zaproponuj przyczynę

To ty złapałeś błąd, więc może możesz zasugerować potencjalne przyczyny, dla których się tam znajduje. Może błąd pojawia się dopiero po napotkaniu określonego zdarzenia, a może dzieje się tylko na urządzeniach mobilnych.

Nie zaszkodzi też zbadać bazę kodu i być może zidentyfikować przyczynę problemu. Wtedy Twój problem zostanie zamknięty znacznie szybciej i prawdopodobnie zostaniesz przypisany do powiązanego PR.

Komunikowanie się z klientami

Możesz pracować jako wolny strzelec solo, a może jesteś głównym programistą w małym zespole. W obu przypadkach załóżmy, że jesteś odpowiedzialny za kontakt z klientami w projekcie. 

Teraz stereotyp programisty mówi, że jesteśmy kiepskimi komunikatorami. Jesteśmy znani z tego, że używamy zbyt technicznego żargonu, mówimy innym, co jest, a co nie jest możliwe, a nawet stajemy się defensywni, gdy ktoś kwestionuje nasze podejście.

Jak więc złagodzić ten stereotyp? Zapytaj klientów, czego chcą i zawsze słuchaj ich opinii. Oto jak to zrobić.

Zadaj właściwe pytania

Zacznij od upewnienia się, że Ty i klient jesteście na tej samej stronie:

• Kto jest waszym dobiorcą docelowym?
• Jaki jest cel witryny?
• Kto jest Twoim najbliższym konkurentem i co robi dobrze?

Zadawanie pytań to również dobry sposób na pozytywne pisanie, szczególnie w sytuacjach, gdy nie zgadzasz się z opinią lub decyzją klienta. Zadawanie pytań zmusza tę osobę do popierania własnych twierdzeń, a nie atakowania jej poprzez obronę własnego stanowiska:

• Czy zgadzasz się z tym, nawet jeśli wiąże się to z dodatkowymi kosztami wydajności?
• Czy przeniesienie komponentu pomaga nam lepiej osiągnąć nasz cel?
• Świetnie, kto jest odpowiedzialny za utrzymanie tego po premierze? 
• Czy wiesz od razu, czy kontrast między tymi dwoma kolorami spełnia standardy WCAG AA?

Pytania są o wiele bardziej niewinne i promują ciekawość zamiast wrogości.

Sprzedać się

Jeśli przedstawiasz ofertę potencjalnemu klientowi, będziesz musiał przekonać go, aby cię zatrudnił. Dlaczego klient miałby wybrać Ciebie? Ważne jest, aby określić następujące elementy:

• Kim jesteś
• Co robisz
• Dlaczego dobrze pasujesz do tej pracy
• Linki do odpowiedniej pracy, którą wykonałeś

A kiedy już dostaniesz pracę i będziesz musiał napisać umowę, pamiętaj, że nie ma bardziej onieśmielających treści niż garść prawników. Mimo że jest napisany dla projektów projektowych, Zabójca kontraktowy może być dobrym punktem wyjścia do napisania czegoś bardziej przyjaznego.

Twoja dbałość o szczegóły może być różnicą między Tobą a innym deweloperem próbującym wygrać ten sam projekt. Z mojego doświadczenia wynika, że ​​klienci równie łatwo zatrudnią programistę, z którym uważają, że spodoba im się praca, niż tego, który jest technicznie najbardziej kompetentny lub doświadczony w tej pracy.

Pisanie mikrokopii

Mikrokopia to sztuka pisania przyjazna dla użytkownika UI komunikaty, takie jak błędy. Założę się, że były chwile, w których jako programista musiałeś pisać komunikaty o błędach, ponieważ były one wstrzymywane przez całą drogę do czasu uruchomienia.

Być może dlatego czasami widzimy takie błędy:

Error: Unexpected input (Code 693)

Błędy to ostatnia rzecz, z którą mają się zmierzyć Twoi użytkownicy. Ale one się zdarzają i nic na to nie poradzimy. Oto kilka wskazówek, jak poprawić swoje umiejętności mikrokopiowania.

Unikaj technicznego żargonu

Większość ludzi nie wie, czym jest serwer, podczas gdy 100% programistów wie. Dlatego nie jest niczym niezwykłym, że w komunikacie o błędzie pojawiają się nietypowe terminy, takie jak API lub „przekroczenie limitu czasu”.

O ile nie masz do czynienia z klientem technicznym lub bazą użytkowników, prawdopodobnie większość użytkowników nie ukończyła kursu informatyki i nie wie, jak działa Internet i dlaczego dana rzecz nie działa. Stąd błąd.

Dlatego dobry komunikat o błędzie nie powinien wyjaśniać dlaczego coś poszło nie tak, ponieważ takie wyjaśnienia mogą wymagać użycia przerażających terminów technicznych. Dlatego bardzo ważne jest unikanie technicznego żargonu.

Nigdy nie obwiniaj użytkownika

Wyobraź sobie: próbuję zalogować się na twoją platformę. Otwieram więc przeglądarkę, odwiedzam twoją stronę i wprowadzam swoje dane. Następnie dowiaduję się: „Twój e-mail/hasło jest nieprawidłowe”.

Nawet jeśli myślenie, że to przesłanie jest wrogie, wydaje się dramatyczne, podświadomie sprawia, że ​​czuję się głupio. Microcopy mówi, że obwinianie użytkownika nigdy nie jest w porządku. Spróbuj zmienić swoją wiadomość na coś mniej ostrego, jak ten przykład zaadaptowany z loginu Mailchimp: „Przepraszam, ta kombinacja e-mail-hasło jest niewłaściwa. Pomożemy Ci odzyskać konto”.

Chciałbym również dodać, jak ważne jest unikanie WIELKICH LITER i wykrzykników! Jasne, można je wykorzystać do przekazania podekscytowania, ale w mikrokopii wywołują poczucie wrogości wobec użytkownika.

Nie przytłaczaj użytkownika

Używanie humoru w swojej mikrokopii to dobry pomysł! Potrafi rozjaśnić nastrój i jest łatwym sposobem na ukrócenie negatywności wywołanej nawet najgorszymi błędami.

Ale jeśli go nie używasz doskonale, może się to wydawać protekcjonalne i obraźliwe dla użytkownika. To tylko duży ryzyko do podjęcia.

Mailchimp mówi to dobrze:

[D] nie staraj się żartować — wymuszony humor może być gorszy niż żaden. Jeśli nie masz pewności, zachowaj kamienną twarz.

(podkreślenie moje)

Pisanie dostępnych znaczników

Moglibyśmy z łatwością poświęcić cały artykuł na temat dostępności i jej związku z pisaniem technicznym. Heck, dostępność jest często uwzględniana w przewodnikach po stylu treści, w tym tych dla Microsoft i MailChimp.

Jesteś programistą i prawdopodobnie wiesz już tak dużo o dostępności. Możesz nawet być jednym z bardziej sumiennych programistów, dzięki którym dostępność jest podstawową częścią Twojego przepływu pracy. Mimo to niewiarygodne jest, jak często kwestie dostępności są odkładane na dalszy plan, bez względu na to, jak ważne jest, jak wszyscy wiemy, że udostępnianie doświadczeń online obejmujących wszystkie umiejętności jest niewiarygodne.

Tak więc, jeśli zauważysz, że wdrażasz cudzy copywriting do swojego kodu, piszesz dokumentację dla innych programistów, a nawet piszesz UI kopiuj siebie, pamiętaj o podstawowych najlepszych praktykach dotyczących dostępności, ponieważ uzupełniają one wszystkie inne porady dotyczące pisania technicznego.

Rzeczy jak:

Andy Bell oferuje stosunkowo małe rzeczy, które możesz zrobić, aby treści były bardziej dostępnei warto je sprawdzić. I tylko dla kopnięć, John Rhea popisuje się kilkoma fajnymi sztuczkami edycyjnymi które są możliwe, gdy pracujemy z semantycznymi elementami HTML.

Wnioski

To było sześć sposobów, które pokazują, w jaki sposób pisanie techniczne i rozwój zbiegają się. Chociaż przykłady i porady mogą nie być nauką o rakietach, mam nadzieję, że okazały się one przydatne, niezależnie od tego, czy chodzi o współpracę z innymi programistami, prowadzenie własnej pracy, pisanie własnej kopii w mgnieniu oka, czy nawet sporządzanie propozycji projektu, między innymi rzeczy.

Najważniejsze: wyostrzenie umiejętności pisania i włożenie dodatkowego wysiłku w pisanie może sprawić, że staniesz się lepszym programistą.

Zasoby techniczne dotyczące pisania

Jeśli interesuje Cię pisanie techniczne:

Jeśli interesuje Cię copywriting:

Jeśli interesuje Cię mikrokopia:

Jeśli chcesz skorzystać z profesjonalnego przewodnika po stylu, aby poprawić swoje pisanie:

Jeśli interesuje Cię pisanie o ułatwieniach dostępu: