Geliştiriciler İçin Dokümantasyon İş Akışı Nasıl Otomatikleştirilir

Bu öğreticiden en iyi şekilde yararlanmak için Git, GitHub ve Linux ile komut satırına aşina olmalısınız.

Yüksek Kaliteli Dokümantasyona Neden Önem Vermelisiniz?

Birçok ekip belge yazmakla uğraşır. Bir çerçeveyi kontrol etmeye gittiğinizde, belgeler genellikle güncelliğini yitirmiş veya belirsiz olacaktır. Bu, bir ekip üyesi bir özellik eklemeye çalıştığında dahili hüsrana yol açabilir, ancak yetersiz dokümantasyon nedeniyle mevcut özelliğin nasıl çalıştığını anlamıyorlar. Bu, işte verimsiz saatlere yol açabilir.

Kötü belgeler aynı zamanda iyi bir müşteri deneyiminden de ödün verir. Geliştiricinize Sorun'un yazarı ve Twilio'nun kurucusu Jeff Lawson'a göre, bir API'yi ürün olarak satıyorsanız, dokümantasyon teknik paydaşlar için nihai reklamdır . IBM, belgelerin önemi üzerine bir araştırma yaptı ve ankete katılanların %90'ı satın alma kararlarını ürün belgelerinin kalitesine göre verdiklerini itiraf etti.

İyi belgeler yazmak, geliştirici ve müşteri deneyimleri için önemlidir.

Belgeleme Bu Kadar Önemliyse, O halde Mühendislik Ekipleri Neden Önceliğini Düşürüyor?

Belge yazmak, geliştiricileri "akışın" dışına çıkarabilir. Belgeler genellikle ana kod tabanının dışında bulunur ve bulunması ve güncellenmesi zahmetlidir. Bunu bir Excel elektronik tablosuna veya tescilli bir CMS'ye koymak nadir değildir.

Dokümantasyonun otomatikleştirilmesi ve dokümantasyon iş akışının iyileştirilmesi bunu düzeltir.

Belgeleri Yüksek Düzeyden Otomatikleştirme

Otomatik belgeleme ne anlama geliyor? Ortak yazılım geliştirme uygulamalarını benimsemek anlamına gelir. Belgeleri otomatikleştirdiğinizde:

• belgelerinizi Markdown'da yazmak;
• hataları düzeltme ve güncellemeleri dağıtma gibi görevleri çalıştırmak için sürekli entegrasyon ve sürekli dağıtım (CI/CD) ardışık düzeni kullanma (bu öğreticide GitHub Eylemlerini vurgulayacağız);
• Bir stil rehberi uygulamak ve yaygın dilbilgisi hatalarını düzeltmek için Vale gibi araçlar uygulamak.

Stil Kılavuzları

Stil kılavuzunu otomatikleştirmek için Vale ve GitHub Actions gibi araçları kullanmadan önce, stil kılavuzunun tam olarak ne olduğunu tanımlamak için biraz zaman ayıralım.

Belgeler yazarken bu duyguyu biliyor musunuz ve bir şeyler biraz ters görünüyor mu? Açıklamalarınız belgelerin geri kalanına uymuyor, ancak neden yanlış olduklarını tam olarak açıklayamıyorsunuz. Yazı kavramı açıklıyor, ancak uygun görünmüyor.

Bu hissi hissettiğinizde sesiniz ve tonunuz bozuk olabilir . Kalite güvencesi, mühendislik ve ürün ekipleri tarafından düzenlenmiş belgeler geliştiriyor olsanız bile, sesi ve tonu hassaslaştırmak, yazı sesini tutarlı hale getirmenin bir yoludur. Aşağıda, Torrey Podmajersky'nin UX için Stratejik Yazma kitabından alınan, şehir içi otobüs uygulaması TAPP'tan örnek bir stil kılavuzu bulunmaktadır.

TAPP bir toplu taşıma uygulamasıdır (otobüsler ve trenler için). Tablonun başlığı, TAPP'ın bir şirket olarak değerlerini, verimli, güvenilir ve erişilebilir olmasını açıklar. Tablonun sol tarafı, stil kılavuzunun kapsadığı farklı bölümleri listeler: kavramlar, sözcük dağarcığı, ayrıntılı bilgi, dilbilgisi ve noktalama işaretleri.

Bunlar birlikte bir stil rehberi oluşturur. Başlık, değerleri tanıtır ve tablonun sol tarafı, herhangi bir yazılı materyalde bulabileceğiniz farklı bileşenleri gösterir: kelime bilgisi, dilbilgisi ve noktalama işaretleri. Bu stil kılavuzunun güzelliği, mühendislerin ve metin yazarlarının, Tapp'ın marka kimliğini tanıtmak için hangi büyük harflerin kullanılacağını ve hangi noktalama işaretlerinin kullanılacağını açıkça bilmeleridir.

Teknik Yazı Stili Kılavuzu

Tüm stil kılavuzları tablolarda gelmez. Microsoft, kısaltmalardan önyargısız iletişime ve sohbet robotlarına kadar her şeyi kapsayan kapsamlı bir kılavuz görevi gören eksiksiz bir web sitesine sahiptir. Stil kılavuzuna sahip olan tek şirket Microsoft değil elbette. Google'ın da bir tane var.

Stil Kılavuzlarıyla İlgili Sorun

Stil kılavuzları, dokümantasyon konusunda ciddi olan şirketler için harika bir başlangıç ​​noktasıdır. Geliştiricilerin, öne sürdükleri önemli bir özellik hakkında tam olarak nasıl yazacakları konusunda sahip olabilecekleri birçok kafa karışıklığını çözüyorlar.

Stil kılavuzlarıyla ilgili sorun, yazma sürecine sürtüşme eklemeleridir. Ben dahil birçok yazar, her sorusu olduğunda yazmayı bırakıp stil rehberine bakma zahmetine girmez. Bazen bir stil kılavuzu hantal ve başvurulması çok zordur - örneğin, Microsoft Stil Kılavuzu bin sayfadan fazladır!

Dokümantasyon için Linterler ve CI/CD

Bir programcıysanız, muhtemelen linterlere aşinasınızdır. Linterler, ekibinizde kodlama standartlarını uygulamak için ideal bir yoldur. Aynı şey belgeler için de geçerlidir. Bir linter oluşturduğunuzda, belgeleriniz için bir kalite ölçütü belirliyorsunuz. Bu dersimizde Vale linterini kullanacağız.

Bir linter ile birlikte bir tür dokümantasyon otomasyonu kullanmak yaygındır. Bu bağlamda otomasyon dediğimizde sürekli entegrasyon ve sürekli dağıtım (CI/CD) iş akışından bahsediyoruz. CI , belgelerin oluşturulmasını ve test edilmesini otomatikleştirir. CD, kodun serbest bırakılmasını otomatikleştirir.

Bir CI/CD iş akışını uygulamak için birçok farklı türde uygulama kullanabilirsiniz. Bu eğitimde, belge linterimizi çalıştırmak için GitHub Eylemlerini kullanacağız. GitHub Eylemleri, CI'yi doğrudan GitHub deposunda çalıştırır, bu nedenle CircleCI veya Travis gibi üçüncü taraf bir uygulama kullanmaya gerek yoktur.

Son olarak, GitHub Eylemleri olaya dayalıdır, yani biri bir çekme isteği veya sorun yazdığında olduğu gibi bir şey olduğunda tetiklenirler. Örneğimizde, biri değişiklikleri ana dallarına gönderdiğinde GitHub eylemi gerçekleşecektir.

GitHub Eylemleri

İlk önce bir GitHub deposu oluşturun. Ardından, yerel olarak bir klasör ve cd oluşturun.

 mkdir automated-docs cd automated-docs

Klasöre girdikten sonra Git dizinini başlatın.

 git init

Depoyu başlattıktan sonra, klasörünüze bir iş akışı dizini oluşturmaya devam edin.

 mkdir .github/ && cd .github/ && mkdir workflows/ && cd workflows/

İş akışları, tüm GitHub eylemlerimizi depolayacağımız yerdir. Bir workflows klasörü oluşturduktan sonra yeni bir iş akışı yapın. Bu iş akışını vale.yml olarak adlandıracağız.

 touch vale.yml

Vale.yml bir YAML dosyasıdır. Bu iş akışı dosyasında, eylemleri ve işleri dahil edeceğiz.

Şimdi vale.yml favori metin düzenleyicinizde açın.

 nano vale.yml

Aşağıdakileri kopyalayıp vale.yml içine yapıştırın ve bağlam ve sözdizimini gözden geçirelim.

 # This is a basic workflow to help you get started with Actions name: CI # Controls when the workflow will run on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] pull_request: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project. env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

• name
  İş akışımızın adı veya dediğimiz şey budur. Bu bir dizedir.
• on
  Bu, iş akışını ve tetikleyicileri kontrol eder.
• jobs
  Eylemlerimizi ayarlayıp kontrol ettiğimiz yer burasıdır. Eylemlerimizin yürütüleceği ortamı seçiyoruz - genellikle Ubuntu ile gitmek iyi bir seçimdir. Ve burada eylemlerimizi ekleyeceğiz.

Merak ediyorsanız, GitHub'ın diğer tüm iş akışı sözdizimi ve değişkenleri hakkında bir kılavuzu vardır.

Bu bölümde, elimizde:

• GitHub eylemlerinin ne olduğunu öğrendi,
• ilk GitHub iş akışımızı oluşturduk,
• GitHub iş akışı YAML dosyasının en önemli kısımlarını belirledi.

Ardından GitHub iş akışımızı Vale'yi kullanacak şekilde özelleştireceğiz.

GitHub Eylemleri Dosyasında Vale Kurulumu

Temel iş akışı dosyasını kopyaladıktan sonra, Vale eylemlerini kullanmaya başlayabilmemiz için onu özelleştirmenin zamanı geldi. Yapılacak ilk şey, YAML dosyasının adını Docs-Linting olarak değiştirmek.

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting

Ardından, biri değişikliklerini GitHub'daki ana şubeye aktardığında Vale testini çalıştırmak istiyoruz. Birisi bir çekme isteği oluşturduğunda testin çalışmasını istemiyoruz, bu nedenle YAML dosyasının o bölümünü sileceğiz.

 on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ]

jobs bölümü, iş akışı dosyasının ana bölümüdür ve GitHub eylemlerini çalıştırmaktan sorumludur.

 jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master

Bu eylemler Ubuntu'nun en son sürümünde çalışacak. Checkout eylemi, GitHub iş akışının ona erişmesi için depoyu kontrol eder.

Şimdi GitHub iş akışımıza bir Vale eylemi ekleme zamanı.

 - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Eylemimize Vale adını verdik. uses değişkeni, hangi Vale sürümünü uygulayacağımızı gösterir - ideal olarak en son sürümü kullanmalıyız. with değişkeninde, debug true olarak ayarladık.

styles bölümü bize Vale'ye bir stil kılavuzu ekleme seçeneği sunar. Bu örnekte, write-good ve Microsoft'un resmi stil kılavuzunu kullanacağız. Diğer stil kılavuzlarını da kullanabileceğimizi unutmayın.

Bu GitHub eyleminin son kısmı env . Bu GitHub eylemini çalıştırmak için bir gizli belirteç eklememiz gerekiyor.

Sonuç şöyle görünmelidir:

 # This is a basic workflow to help you get started with Actions. name: Docs-Linting # Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: branches: [ main ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: jobs: prose: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@master - name: Vale uses: errata-ai/[email protected] with: debug: true styles: | https://github.com/errata-ai/write-good/releases/latest/download/write-good.zip https://github.com/errata-ai/Microsoft/releases/latest/download/Microsoft.zip env: GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

Değişiklik yapmayı bitirdikten sonra dosyayı kaydedin, Git'e gidin ve değişikliklerinizi GitHub'a aktarın.

 git add .github/workflows/vale.yml git commit -m "Added github repo to project" git push -u origin main

Bu bölümde özetlemek gerekirse:

• main dala yeni kod bastığımızda gerçekleşecek eylemi tetikledi;
• debug true olarak ayarlayan ve stil kılavuzlarını tanımlayan bir Vale eylemi ekledi;
• bir GitHub belirteci eklendi;
• değişiklikleri taahhüt etti ve GitHub'a aktardı.

Bir sonraki bölümde bir Vale yapılandırma dosyası oluşturacağız.

Vale Yapılandırma Dosyasını Ayarlama

Projenizin dizininin köküne gidin ve ardından touch .vale.ini . .vale.ini bir metin düzenleyicide açın. Aşağıdakileri kopyalayıp .vale.ini içine yapıştırın:

 StylesPath = .github/styles MinAlertLevel = warning [formats] Markdown = markdown [*.md] BasedOnStyles = write-good, Microsoft

• StylesPath = .github/styles
StylesPath , Vale stillerinin yolunu verir.
• MinAlertLevel = warning
  Minimum uyarı düzeyi, uyarılardaki önem derecesini gösterir. Seçenekler suggestion , warning ve error .
• [formats]
Markdown = markdown , formatı Markdown olarak ayarlar.
• [*.md]
BasedOnStyles = write-good, Microsoft yazma özelliğini ve Microsoft stil kılavuzunu .md ile biten tüm Markdown dosyalarında çalıştırır.

Bu kurulum minimumdur. Vale'yi yapılandırma hakkında daha fazla bilgi edinmek istiyorsanız, belgelere gidin.

Değişiklik yapmayı tamamladığınızda, dosyayı kaydedin ve taahhütte bulunarak GitHub'a gönderin.

 git add .vale.ini git commit -m "Added Vale config file" git push -u origin main

Bu bölümde, bir Vale yapılandırma dosyasının içindekileri öğrendik. Şimdi örnek belgeler oluşturma zamanı.

Dokümantasyon Oluşturma ve Vale GitHub Eylemlerini Tetikleme

Şimdi Vale ve GitHub Actions'ı iş başında görme zamanı! Bir Markdown dosyası oluşturacağız ve onu metinle dolduracağız. Ve metnimizi DeLorean Ipsum'dan alacağız.

Projenizin köküne gidin ve ardından touch getting-started.md . Başlangıç ​​dosyasını oluşturduktan getting-started , DeLorean Ipsum'a gidin ve dokümantasyonunuz için bazı yapay metinler oluşturun. Ardından, metin düzenleyicinize dönün ve metni getting-started-md içine yapıştırın.

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all exactly twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Dosyayı kaydedin, taahhüt edin ve GitHub'a gönderin.

 git add getting-started.md git commit -m "first draft" git push -u origin main

Değişiklikleri yükledikten sonra, deponuzun bulunduğu GitHub'a gidin. Actions sekmesine gidin.

Sol tarafta tüm iş akışlarınızı göreceksiniz. vale.yml dosyasına koyduğumuz adın aynısı olan Docs-Linting adında yalnızca bir tane var.

Belgeleri GitHub'a aktardığımızda eylemi tetikleyeceğiz.

İşlem sorunsuz bir şekilde yürütüldüyse yeşil bir onay işareti alırız.

Tam bir rapor almak için "Eklenen dokümanlar"ı tıklayın.

11 uyarı aldığımızı göreceksiniz. Gelelim “gelincik kelime” uyarısına. Metin düzenleyiciye geri dönün, getting-started.md açın ve "tam olarak" kelimesini silin.

 # Getting Started Guide I can't play. It's my dad. They're late. My experiment worked. They're all twenty-five minutes slow. Marty, this may seem a little foreward, but I was wondering if you would ask me to the Enchantment Under The Sea Dance on Saturday. Well, they're your parents, you must know them. What are their common interests, what do they like to do together? Okay. Are you okay? Whoa, wait, Doc. What, well you mean like a date? I don't wanna see you in here again. No, Biff, you leave her alone. Jesus, George, it's a wonder I was ever born. Hey, hey, keep rolling, keep rolling there. No, no, no, no, this sucker's electrical. But I need a nuclear reaction to generate the one point twenty-one gigawatts of electricity that I need. I swiped it from the old lady's liquor cabinet. You know Marty, you look so familiar, do I know your mother?

Değişiklikleri kaydedin, Git'e kaydedin ve dosyanın yeni sürümünü GitHub'a gönderin. GitHub eylemini tetiklemelidir .

“Deleted the Weasel word” yazısına tıklarsak artık sadece 10 uyarımız olduğunu ve “gelincik word” uyarısının kalktığını göreceğiz. Yaşasın!

Bitirdik ve çok yol kat ettik. Bu bölümde, elimizde:

• Vale GitHub Actions depomuza ek belgeler,
• Vale GitHub eylemini tetikledi,
• Vale tarafından üretilen bir hatayı düzeltti ve değişikliği GitHub'a geri itti.

Çözüm

Giderek uzaklaşan bir dünyada, iyi dokümantasyona ve iyi dokümantasyon iş akışına öncelik vermek önemlidir. Öncelikle bir stil rehberi oluşturarak “iyi”nin ne olduğunu tanımlamanız gerekir. Belgelerinizin kurallarını anladıktan sonra, otomatikleştirme zamanı.

Belgeler, kod tabanınız gibi ele alınmalıdır: sürekli olarak yinelenen ve en son güncellediğinizden biraz daha iyi hale gelen canlı bir çalışma grubu.