Geliştiriciler için Teknik Yazı

HTML, CSS, JavaScript, Python, PHP, C++, Dart — orada çok fazla programlama dili var ve hatta bunların birçoğunda tamamen akıcı olabilirsiniz! Ancak daha fazla ve daha iyi kod yazmayı hedefledikçe, günlük dilde yazma ve iletişim kurma şeklimiz giderek daha önemli hale geliyor… ve belki de gözden kaçıyor.

Kod hakkında ve çevresinde yazma şeklimiz tartışmasız kodun kendisi kadar önemlidir. Ve bu çizgiye düştüğünüz yere rağmen, sözlerimizin kodun etkinliğine hem yardım etme hem de zarar verme potansiyeline sahip olduğu konusunda hemfikiriz.

Bu makalede, görünüşte farklı olan bu iki alanın - programlama ve yazmanın - nasıl bir araya gelip geliştirici becerilerimizi nasıl bir sonraki seviyeye taşıyabileceğini ana hatlarıyla belirtmek istiyorum.

Bekle, teknik yazı mı? Evet, demek istediğim tam olarak bu. Hepimizin bir anlamda yazar olduğumuza gerçekten inanıyorum. Ve sizi nasıl daha iyi bir geliştirici ve iletişimci yapabileceğine dair ipuçları, tavsiyeler ve örnekler içeren bir başlangıç ​​kitabı vermek için buradayım.

Teknik yazı her yerde

Geçen yıl, popüler Mac Git istemcisi Tower'ın arkasındaki ekip, 4,000'den fazla geliştiriciyle anket yapıldı ve yaklaşık %50'sinin günde 3-6 saat arasında kod yazarak geçirdiğini buldu.

Ve evet, bu oldukça niş bir grubu sorgulayan bir anket, ancak çoğumuzun bu aralıkta bir yere düştüğünü hayal ediyorum. Durum ne olursa olsun, bir geliştirici 24/7 kod yazmaz, çünkü bu anketin gösterdiği gibi, başka şeyler yapmak için bolca zaman harcıyoruz.

Bu şunları içerebilir:

• yeni bir özelliğin demosunu yapmak,
• bu yeni özelliği belgelemek,
• bu yeni özellikle ilgili bir iş biletini güncellemek veya
• Bu yeni özelliği desteklemek için biriktirme çalışması.

Tabii ki, banyo molaları ve Wordle için her zaman zaman vardır.

Her neyse, tipik olarak yaptığımız şeylerin çoğu, ekibiniz, meslektaşlarınız, müşterileriniz, kullanıcılarınız ve diğer geliştiriciler gibi insanlarla iletişim kurmayı içerir.

Bu yüzden zamanımızın büyük bir bölümünü insanlarla iletişim yoluyla geçiriyoruz. sözler bilgisayarlarla kurduğumuz iletişimin yanı sıra kod. Kelimeler yazı dilidir. Ve eğer sözlerimizi daha iyi yazsaydık, daha iyi iletişim kurardık. Daha iyi iletişim kurduğumuzda, istediğimizi elde etme olasılığımız daha yüksektir.

Bu Teknik Yazma 101.

Ve burada bitmiyor bile.. Bazı programcılar kendi ürünlerini yapmayı da severler, bu da pazarlamayı işlerinin bir parçası haline getirmeleri gerektiği anlamına gelir. Teknik yazının da bunda büyük rolü var. Yani evet. Bence teknik yazının olduğunu söylemek oldukça adil gerçekten her yerde.

İyi gramer nedir?

Piyasada bu kadar çok programlama dili varken, istediğimiz son şey bir tane daha öğrenmek.

Dilbilgisi İngilizcenin ayrılmaz bir parçasıdır ve iletişimin tüm potansiyelini ortaya çıkarır. Bizi daha resmi, profesyonel ve tutarlı kılıyor.

Size dil hakkında kısa bir özet vereyim.

İngilizce sözdizimi

Tıpkı programlama dilleri gibi, İngilizce'nin de iyi tanımlanmış bir sözdizimi vardır ve kelimelerle başlar.

Kelimeler İngilizcenin yapı taşlarıdır ve sekiz kovaya ayrılırlar:

Bunlar gibi düşün UI bileşenler: tam ve sağlam bir cümle oluşturmak için hareket ettirebileceğiniz modüler parçalardır, aynı şekilde eksiksiz ve sağlam bir cümleyi bir araya getirebilirsiniz. UI. Tüm bileşenlerin her zaman orada olması mı gerekiyor? Kesinlikle değil! Tıpkı bir arayüzde yaptığınız gibi, deneyimi tamamlamak için ihtiyacınız olan parçalarla bir cümle kurun.

ses ve ton

Kelime bilgisi, noktalama işaretleri, cümle yapısı ve kelime seçimi. Bunların hepsi İngilizce'nin bileşenleridir. Bunları fikir paylaşmak, arkadaşlarımız ve ailemizle iletişim kurmak ve iş arkadaşlarımıza e-posta göndermek için kullanırız.

Ama dikkate almak çok önemli ses mesajlarımızdan. Bir ünlem işaretinin bir mesajın tonunu nasıl tamamen değiştirebileceği şaşırtıcı:

1. Programlamayı severim.
2. I sevmek programlama! :)

Sesi tonla karıştırmak kolaydır ve bunun tersi de geçerlidir.

ses bağlama bağlı olarak kelime seçimimizi ilgilendiren şeydir. Örneğin, yeni başlayanlar için bir öğretici, arkadaşça bir ses iletmek için argo ve gayri resmi bir dil kullanmaya daha yatkınken, belgeler doğrudan konuya girmek için resmi, ciddi ve profesyonel bir şekilde yazılabilir.

Aynı mesaj, iki farklı sesle yazılmış:

• Eğlence: “Sosyal ağınızı genişletin ve şu anda nelerin trend olduğu konusunda güncel kalın.”
• Ciddi: "En büyük sosyal ağ uygulamalarından ve çevrimiçi iş piyasasından birinde iş bulun."

Yanlışlıkla küçümseyici, saldırgan ve profesyonelce olmayan mesajlar yazmak alışılmadık bir durum değildir. burası ton devreye giriyor. Mesajlarınızı yüksek sesle okuyun, başkalarının bunları sizin için okumasını sağlayın ve noktalama işaretlerinizi ve cümle yapınızı deneyin. Böylece ses tonunuzu geliştirirsiniz.

İşte bunu düşünmenin başka bir yolu: sesiniz asla değişmez, ancak tonunuz değişir. Sesiniz, bir kişi olarak kim olduğunuza benzer, ton ise belirli bir durumda nasıl tepki verdiğinizdir.

Aktif ve pasif ses

Bir cümle her zaman bir aktör, bir fiil ve bir hedef içerir. Bunların gelme sırası, cümlenin aktif mi yoksa pasif bir sesle mi yazıldığını belirler.

Oyuncu ilk sırada gelir aktif ses. Örneğin: "CSS arka planı boyar."

Aktif bir ses kullanan cümleler, emsallerinden daha basittir. Daha net, daha kısa ve daha anlaşılırlar - doğrudan konuya giren daha profesyonel bir ses için mükemmeller.

Bir ile pasif ses, aktör en son gelir. (Orada ne yaptığımı gördünüz mü?) Bunun anlamı, aktörümüz - bu durumda CSS - sona şu şekilde gelir: "Arka plan CSS tarafından boyanmıştır."

Okuyucular genellikle pasif bir sesi kafalarında aktif bir sese dönüştürerek daha fazla işlem süresi sağlar. Aktif bir sesle yazmanın daha iyi olduğunu duyduysanız, genellikle nedeni budur. Teknoloji yazarları, araştırmadan alıntı yapmak gibi çok az istisna dışında çoğu zaman aktif sesi tercih ederler: “Önerildi ki…”

Ancak bu, her zaman aktif bir ses için çabalamanız gerektiği anlamına gelmez. Aynı paragrafta bile birinden diğerine geçmek, etkili bir şekilde kullanıldığında içeriğinizin bir cümleden diğerine daha sorunsuz bir şekilde akmasını sağlayabilir.

Hatalardan kaçınmak

Dilbilgisi tamamen dilin yapısı ve doğruluğu ile ilgilidir ve bunu başarmak için belgenizi hızlı bir şekilde yeniden okumaktan daha iyi bir şey yoktur. Yazılarınızı yazım hatalarından, dilbilgisi sorunlarından ve anlamsal kusurlardan kurtarmak çok önemlidir.

Bu makalenin sonunda, profesyonellerin yazım hatalarından kaçınmak için kullandıkları paha biçilmez araçları size göstereceğim. Açıkçası, bugünlerde hemen hemen her şeyde yerleşik yazım denetleyicileri var; kod düzenleyicilerimiz, hataları önlemeye yardımcı olmak için yazım denetimi ve linting eklentilerine bile sahiptir. 

Ama dilbilgisi ile ilgili her şey için tek durak bir araç arıyorsanız, Grammarly en çok kullanılan araçlardan biridir. Bunun için ya da başka bir şey için geri tepme almıyorum. Temiz ve net kod yazmak için Emmet, eslint veya diğer herhangi bir linter'i nasıl kullandığınıza benzer şekilde, birçok editör ve yazarın temiz ve net içerik yazmak için kullandığı gerçekten harika bir araçtır.

Kod yorumları yazma

Diğer geliştiriciler için yazdığımız şeyler, koda ne yazdığımız, kodu nasıl açıkladığımız veya bir kod parçası hakkında nasıl geri bildirim verdiğimiz olsun, işimizin genel kalitesi üzerinde büyük bir etkiye sahip olabilir.

Her programlama dilinin yorum yazmak için standart bir dizi özellik ile gelmesi ilginçtir. Kodun ne yaptığını açıklamalılar. Bununla, bunun gibi belirsiz yorumları kastetmiyorum:

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

Bunun yerine, daha fazla bilgi sağlayan yorumları kullanın:

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

Her şey bağlamla ilgili. “Ne tür bir program yapıyorum?” tam olarak kendinize sormanız gereken türden bir soru.

Yorumlar değer katmalı

Bir kod yorumunu neyin “iyi” yaptığına bakmadan önce, tembel yorumların iki örneği:

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

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

Bir yorumun amacının bir kod parçasına değer katmak olduğunu unutmayın, onu tekrarlamak değil. Bunu yapamıyorsanız, kodu olduğu gibi bırakmanız daha iyi olur. Bu örnekleri "tembel" yapan şey, yalnızca kodun açıkça ne yaptığını yeniden ifade etmeleridir. Bu durumda, yorumlar gereksizdir çünkü bize zaten bildiklerimizi söylerler - değer katmazlar!

Yorumlar mevcut kodu yansıtmalıdır

Büyük projelerde güncelliğini yitirmiş yorumlar nadir görülen bir durum değildir; söylemeye cesaret et çoğu projeleri.

David'i, bir programcı ve takılmak için her yönden havalı bir adam olarak hayal edelim. David, dizelerin listesini A'dan Z'ye alfabetik olarak sıralamak istiyor, bu yüzden JavaScript'te bariz olanı yapıyor:

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

David daha sonra sortWords() öğesinin listeleri Z'den A'ya sıraladığını fark eder. Çıktıyı basitçe tersine çevirebildiği için bu bir sorun değildir:

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

Ne yazık ki, David kod yorumunu güncellemedi.

Şimdi size bu hikayeyi anlatmadığımı ve tüm gördüğünüzün yukarıdaki kod olduğunu hayal edin. Doğal olarak, ikinci kod satırını çalıştırdıktan sonra, "şehirlerin" Z'den A'ya sıralanacağını düşünürdünüz! Bütün bu kafa karışıklığı fiyaskosu bayat bir yorumdan kaynaklandı.

Bu abartılı bir örnek olsa da, yakın bir son teslim tarihine karşı yarışıyorsanız benzer bir şey olabilir (ve genellikle olur). Neyse ki, bu basit bir kural izlenerek önlenebilir… kodu değiştirdiğiniz gibi yorumlarınızı da değiştirin.

Bu, sizi ve ekibinizi birçok sorundan kurtaracak basit bir kuraldır. teknik borç.

Artık kötü yazılmış yorumların neye benzediğini bildiğimize göre, bazı iyi örneklere bakalım.

Yorumlar unidiomatic kodu açıklamalıdır

Bazen doğal işleri yapmanın yolu doğru değil. Programcılar standartları biraz "kırmak" zorunda kalabilirler, ancak bunu yaptıklarında, gerekçelerini açıklayan küçük bir yorum bırakmaları tavsiye edilir:

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

Bu yardımcı olur, değil mi? Bu kodu gözden geçirmekten sorumluysanız, orada ne olduğunu açıklayan o yorum olmadan düzeltmeye istekli olabilirsiniz.

Yorumlar gelecekteki görevleri tanımlayabilir

Yorumlarla yapılacak bir başka yararlı şey de yapılacak daha çok iş olduğunu kabul etmektir.

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

Bu şekilde akışınıza odaklanabilirsiniz. Ve daha sonraki bir tarihte siz (veya bir başkası) geri gelip düzeltebilirsiniz.

Yorumlar kaynağa geri bağlantı verebilir

Demek probleminize StackOverflow'ta bir çözüm buldunuz. Bu kodu kopyalayıp yapıştırdıktan sonra, ileride başvurmak üzere geri dönebilmeniz için size yardımcı olan cevaba bir bağlantı tutmak bazen iyi bir şeydir.

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

Bu önemlidir çünkü çözümler değişebilir. Bozulması durumunda kodunuzun nereden geldiğini bilmek her zaman iyidir.

Çekme istekleri yazma

Çekme istekleri (PRs) herhangi bir projenin temel bir yönüdür. Kod incelemelerinin merkezinde yer alırlar. Ve kod incelemeleri, iyi ifadeler olmadan ekibinizin performansında hızla bir darboğaz haline gelebilir.

İyi PR açıklama özetler ne değişiklik yapılıyor ve neden yapılıyor. Büyük projelerde, bunun gibi bir çekme isteği şablonu vardır. gerçek örnek:

## 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…

belirsiz kaçının PR başlıkları

Lütfen şuna benzeyen başlıklardan kaçının:

• Yapıyı düzelt.
• Hata düzeltildi.
• Yama ekleyin.

Bunlar bile değil girişim hangi yapı, hata veya yama ile uğraştığımızı açıklamak için. Derlemenin hangi bölümünün düzeltildiğine, hangi hatanın ortadan kaldırıldığına veya hangi yamanın eklendiğine dair biraz daha ayrıntı, iş arkadaşlarınızla daha iyi iletişim ve işbirliği kurmak için uzun bir yol kat edebilir. Seviyeyi belirler ve insanları aynı sayfada toplar.

PR başlıklar geleneksel olarak yazılır emir kipi. Bunlar, bütünün tek satırlık bir özetidir. PRve açıklamalılar ne tarafından yapılıyor PR.

İşte bazı iyi örnekler:

• NgOptimizedImage'da özel srcset özniteliklerini destekleyin
• %75 görüntü kalitesine varsayılan görüntü yapılandırması
• Tüm yerleşik ControlValueAccessors için açık seçiciler ekleyin

Uzun kaçının PRs

Büyük PR çok büyük bir açıklama anlamına gelir ve hiç kimse yüzlerce veya binlerce kod satırını gözden geçirmek istemez, bazen sadece her şeyi göz ardı etmek için!

Bunun yerine şunları yapabilirsiniz:

• aracılığıyla ekibinizle iletişim kurun Sorunlar,
• Bir plan yapmak,
• sorunu daha küçük parçalara ayırın veya
• her parça üzerinde ayrı ayrı çalışın PR.

Şimdi daha temiz değil mi?

Ayrıntıları şurada sağlayın: PR vücut

Aksine PR başlık, vücut the dahil olmak üzere tüm ayrıntılar için yer:

• Neden bu PR yapılıyor?
• Bu neden en iyi yaklaşım?
• Yaklaşımdaki eksiklikler ve mümkünse bunları çözmek için fikirler
• Hata veya bilet numarası, kıyaslama sonuçları vb.

Hataları bildirme

Hata raporları, herhangi bir projenin en önemli yönlerinden biridir. Ve tüm harika projeler, kullanıcı geri bildirimleri üzerine kuruludur. Genellikle, sayısız testten sonra bile, çoğu hatayı bulan kullanıcılardır. Kullanıcılar aynı zamanda harika idealistlerdir ve bazen önemli fikirleri vardır; lütfen onları dinleyin!

Teknik projeler için, tüm bunlar sorunları raporlayarak yapılır. İyi yazılmış bir sorunu başka bir geliştiricinin bulması ve yanıtlaması kolaydır.

Örneğin, çoğu büyük proje ile birlikte gelir bir şablon:

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

Ekran görüntülerini toplayın

kullanarak sorunu yakalayın sistemin ekran çekimi yardımcı programı.

Bir ekran görüntüsü ise CLI programında, metnin net olduğundan emin olun. eğer bir UI programı, ekran görüntüsünün doğru öğeleri ve durumları yakaladığından emin olun.

Sorunu göstermek için gerçek bir etkileşim yakalamanız gerekebilir. Eğer durum buysa, deneyin bir ekran kayıt aracı kullanarak GIF'leri kaydedin.

Sorun nasıl yeniden oluşturulur

Programcıların bir hatayı bilgisayarlarında yayındayken çözmeleri çok daha kolaydır. Bu nedenle, sorunu tam olarak yeniden oluşturmaya yönelik adımlarla iyi bir taahhüt gelmelidir.

İşte bir örnek:

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.

Bir neden önerin

Böceği yakalayan sizsiniz, bu yüzden belki de neden orada olduğuna dair bazı olası nedenler önerebilirsiniz. Belki hata yalnızca belirli bir olayla karşılaştıktan sonra gerçekleşir veya belki de yalnızca mobilde gerçekleşir.

Ayrıca kod tabanını keşfetmek ve belki de soruna neyin neden olduğunu belirlemek de zarar veremez. Ardından, Sorununuz çok daha hızlı kapatılacak ve muhtemelen ilgili bölüme atanacaksınız. PR.

müşterilerle iletişim

Tek başına serbest çalışan olarak çalışabilir veya küçük bir ekipte baş geliştirici olabilirsiniz. Her iki durumda da, bir projede müşterilerle arayüz oluşturmaktan sorumlu olduğunuzu varsayalım. 

Şimdi, programcı klişesi, bizler zayıf iletişimcileriz. Aşırı teknik jargon kullandığımız, başkalarına neyin mümkün olup olmadığını söylediğimiz ve hatta birisi yaklaşımımızı sorguladığında savunmaya geçtiğimiz biliniyor.

Peki, bu stereotipi nasıl azaltabiliriz? Müşterilere ne istediklerini sorun ve her zaman geri bildirimlerini dinleyin. İşte bunu nasıl yapacağınız.

Doğru soruları sorun

Siz ve müşterinin aynı sayfada olduğundan emin olarak başlayın:

• Hedef kitleniz kimdir?
• Sitenin amacı nedir?
• En yakın rakibiniz kim ve neleri doğru yapıyorlar?

Soru sormak, özellikle bir müşterinin geri bildirimi veya kararına katılmadığınız durumlarda, olumlu yazmak için de iyi bir yoldur. Soru sormak, o kişiyi, kendi pozisyonunuzu savunarak saldırmak yerine, kendi iddialarını desteklemeye zorlar:

• Ek bir performans maliyeti ile gelse bile buna uygun musunuz?
• Bileşeni taşımak, hedefimizi daha iyi gerçekleştirmemize yardımcı olur mu?
• Harika, lansmandan sonra bunu sürdürmekten kim sorumlu? 
• Bu iki renk arasındaki kontrastın WCAG AA standartlarını geçip geçmediğini önceden biliyor musunuz?

Sorular çok daha masum ve düşmanlığa karşı merakı teşvik ediyor.

Kendini sat

Potansiyel bir müşteriye satış konuşması yapıyorsanız, onları sizi işe almaya ikna etmeniz gerekecek. Müşteri neden sizi seçmeli? Aşağıdakileri belirtmek önemlidir:

• Sen kimsin
• Ne yaptın
• Neden iş için uygunsun
• Yaptığınız ilgili çalışmalara bağlantılar

İşi aldığınızda ve bir sözleşme yazmanız gerektiğinde, bir avuç hukukçudan daha göz korkutucu bir içerik olmadığını unutmayın. Tasarım projeleri için yazılmış olsa da, Sözleşme Katili çok daha dostça bir şeyler yazmak için güzel bir başlangıç ​​noktası olabilir.

Ayrıntılara gösterdiğiniz özen, sizinle aynı projeyi kazanmaya çalışan başka bir geliştirici arasındaki fark olabilir. Tecrübelerime göre, müşteriler, teknik olarak iş için en yetkin veya deneyimli olandan daha fazla çalışmaktan keyif alacaklarını düşündükleri bir geliştirmeyi kolayca işe alacaklardır.

Mikrokopi yazma

mikrokopi kullanıcı dostu yazma sanatıdır UI hatalar gibi mesajlar. Bahse girerim, bir geliştirici olarak, başlatma zamanına kadar arka plana atıldığı için hata mesajları yazmak zorunda kaldığınız zamanlar olmuştur.

Bu yüzden bazen şöyle hatalar görüyoruz:

Error: Unexpected input (Code 693)

Hatalar, kullanıcılarınızın uğraşmasını istediğiniz son şeydir. Ama bunlar oluyor ve bu konuda yapabileceğimiz hiçbir şey yok. Mikrokopi becerilerinizi geliştirmek için bazı ipuçları.

Teknik jargondan kaçının

Çoğu kişi sunucunun ne olduğunu bilmezken programcıların %100'ü bilir. Bu nedenle, bir hata mesajında, örneğin API veya "zaman aşımı yürütme".

Teknik bir müşteri veya kullanıcı tabanıyla uğraşmıyorsanız, kullanıcılarınızın çoğu bilgisayar bilimi kursu almamış ve İnternet'in nasıl çalıştığını ve belirli bir şeyin neden çalışmadığını bilmiyor olabilir. Bu nedenle, hata.

Bu nedenle, iyi bir hata mesajı açıklamamalı neden bir şeyler ters gitti, çünkü bu tür açıklamalar korkutucu teknik terimler kullanmayı gerektirebilir. Bu yüzden teknik jargon kullanmaktan kaçınmak çok önemlidir.

Kullanıcıyı asla suçlama

Şunu hayal edin: Platformunuza giriş yapmaya çalışıyorum. Bu yüzden tarayıcımı açıyorum, web sitenizi ziyaret ediyorum ve bilgilerimi giriyorum. Sonra bana söylendi: "E-postanız/şifreniz yanlış."

Bu mesajın düşmanca olduğunu düşünmek dramatik görünse de, bilinçaltında kendimi aptal gibi hissettiriyor. Mikrokopi, kullanıcıyı suçlamanın asla doğru olmadığını söylüyor. Mesajınızı, Mailchimp'in girişinden uyarlanan bu örnek gibi, daha az parmakla gösterilen bir şeyle değiştirmeyi deneyin: “Üzgünüz, bu e-posta-şifre kombinasyonu doğru değil. Hesabınızı kurtarmanıza yardımcı olabiliriz.”

TÜM BÜYÜK HARF ve ünlem işaretlerinden kaçınmanın önemini de eklemek isterim! Elbette, heyecanı iletmek için kullanılabilirler, ancak mikroskopta kullanıcıya karşı bir düşmanlık duygusu yaratırlar.

Kullanıcıyı bunaltmayın

Mikrokopyanızda mizah kullanmak iyi bir fikirdir! Ortamı yumuşatabilir ve en kötü hataların bile neden olduğu olumsuzlukları dizginlemenin kolay bir yoludur.

Ama eğer kullanmazsan kusursuzca, kullanıcıya küçümseyici ve aşağılayıcı gelebilir. bu sadece bir büyük alma riski.

Mailchimp bunu iyi söylüyor:

[D] Şaka yapma yolundan çıkmayın - zorla mizah hiç olmamasından daha kötü olabilir. Emin değilseniz, düz bir yüz tutun.

(benimki vurgula)

Erişilebilir işaretleme yazma

Erişilebilirlik ve bunun teknik yazıyla nasıl ilişkili olduğu hakkında bir makalenin tamamını kolayca harcayabiliriz. Heck, erişilebilirlik genellikle içerik stili kılavuzlarına dahil edilir. Microsoft ve  .

Bir geliştiricisiniz ve muhtemelen erişilebilirlik hakkında zaten çok şey biliyorsunuzdur. Erişilebilirliği iş akışınızın temel bir parçası haline getiren daha gayretli geliştiricilerden biri bile olabilirsiniz. Yine de, tüm yetenekleri kapsayan erişilebilir çevrimiçi deneyimler yaratmanın ne kadar önemli olduğunu hepimiz bilsek de, erişilebilirlik hususlarının ne kadar sıklıkla ikinci plana atıldığı inanılmaz.

Bu nedenle, kendinizi başka birinin metin yazarlığını kodunuza uygularken, diğer geliştiriciler için belgeler yazarken ve hatta yazarken bulursanız UI kendinizi kopyalayın, teknik yazı için diğer tüm tavsiyeleri tamamladıkları için bazı temel erişilebilirlik en iyi uygulamalarına dikkat edin.

Gibi şeyler:

Andy Bell bazı nispeten sunuyor içeriği daha erişilebilir hale getirmek için yapabileceğiniz küçük şeyler, ve onları kontrol etmek için zaman ayırmaya değer. Ve sadece tekmeler için, John Rhea bazı düzgün düzenleme hileleri gösteriyor anlamsal HTML öğeleriyle çalışırken bu mümkündür.

Sonuç

Bunlar, teknik yazma ve geliştirmenin nasıl örtüştüğünü gösteren altı yoldu. Örnekler ve tavsiyeler roket bilimi olmasa da, diğer geliştiricilerle işbirliği yapmak, kendi işinizi sürdürmek, bir çırpıda kendi kopyanızı yazmak veya hatta bir proje teklifi hazırlamak gibi konularda onları yararlı bulmuşsunuzdur. şeyler.

Sonuç olarak: Yazma becerilerinizi geliştirmek ve yazınıza biraz fazladan çaba harcamak sizi gerçekten daha iyi bir geliştirici yapabilir.

Teknik yazı kaynakları

Teknik yazıyla ilgileniyorsanız:

Metin yazarlığı ile ilgileniyorsanız:

Mikrokopya ile ilgileniyorsanız:

Yazınızı geliştirmek için profesyonel bir stil kılavuzu kullanmakla ilgileniyorsanız:

Erişilebilirlik için yazmakla ilgileniyorsanız: