tech docs

GOV.UK One Login Dokumentasi Teknis

Repo ini berisi dokumentasi untuk membantu para teknolog di departemen pemerintah di atas kapal ke Gov.uk satu login. Ini diterbitkan menggunakan template dokumentasi teknis.

Membuat perubahan konten

Tim penulisan teknis Gov.uk satu memiliki dokumentasi ini dan memiliki tanggung jawab untuk menyetujui perubahan konten. Itu ditulis untuk menjadi pengguna dan memenuhi standar konten GDS, yang berarti mengikuti:

• Bimbingan gov.uk tentang perencanaan, menulis dan mengelola konten
• panduan gaya gov.uk
• panduan gaya teknis gov.uk
• Prinsip Penulisan Jelas Lainnya

Jika Anda bekerja pada GOV.uk satu login, Anda harus menghubungi tim penulis teknologi untuk bantuan dengan perubahan konten kecuali itu kecil dan tidak mempengaruhi perilaku pengguna.

Perubahan konten kecil meliputi:

• Menambahkan klarifikasi untuk meningkatkan pemahaman
• mengoreksi sampel kode
• Memperbaiki tautan atau kesalahan ketik yang rusak

Anda dapat membuat perubahan ini sendiri dan kemudian meminta ulasan penulis teknologi tentang permintaan tarik. Jika Anda tidak yakin apakah suatu perubahan kecil, hubungi kami di saluran Slack #-Technical-penulisan kami.

Membuat perubahan teknis

Tim orkestrasi bertanggung jawab atas pemeliharaan dan kesehatan operasional platform Docs Tech. Anda harus berkonsultasi dengan persetujuan dari setiap perubahan di ruang itu.

Contohnya termasuk:

• Perubahan pada alur kerja aksi gitub
• Perubahan pada penyebaran AWS atau membangun infrastruktur
• pembaruan ketergantungan
• Pembaruan ruby ​​yang tidak mengubah konten

Pratinjau perubahan dokumentasi Anda

Untuk melihat setiap perubahan dan penambahan yang telah Anda buat pada dokumentasi di browser, klon repo ini dan gunakan DockerFile dalam repo ini untuk menjalankan server perantara di mesin Anda tanpa harus mengatur Ruby secara lokal.

Pengaturan ini telah diaktifkan secara langsung, yang berarti perubahan Anda akan diterapkan saat Anda mengedit file di direktori sumber. Satu-satunya pengecualian untuk ini adalah jika Anda membuat perubahan pada config/tech-docs.yml , Anda harus berhenti dan memulai kembali server untuk melihat perubahan Anda dalam pratinjau. Anda dapat menghentikan server dengan Ctrl-C .

Jalankan skrip helper:

./preview-with-docker.sh

Mungkin perlu beberapa menit untuk membangun wadah Docker, terutama jika ini adalah pertama kalinya Anda menjalankan skrip. Ketika server sudah selesai memuat, Anda harus melihat output berikut di terminal:

== View your site at " http://localhost:4567 " , " http://127.0.0.1:4567 "
== Inspect your site configuration at " http://localhost:4567/__middleman " , " http://127.0.0.1:4567/__middleman " /usr/local/bundle/gems/tilt-2.0.11/lib/tilt/redcarpet.

Membuat perubahan pada diagram

Diagram adalah konten, jadi setelah Anda membuat perubahan, Anda harus meminta ulasan dari tim penulisan teknis.

Anda dapat mengedit file draw.io di folder source/images/originals dengan menginstal dan menggunakan aplikasi desktop draw.io.

Gunakan satu file draw.io per diagram.

Menginstal Aplikasi Desktop Draw.io

Jalankan perintah berikut untuk menggunakan aplikasi desktop draw.io dari baris perintah.

 brew install --cask drawio
alias draw.io='/Applications/draw.io.app/Contents/MacOS/draw.io'

Mengedit dan menerbitkan diagram

Ikuti langkah -langkah ini:

1. Buat dan ubah diagram menggunakan draw.io.
2. Simpan file draw.io ke folder source/images/originals .
3. Publikasikan diagram sebagai grafik vektor yang dapat diskalakan (SVG).
4. Simpan file SVG ke folder source/images .

Perintah yang berguna

Perbarui diagram:

 draw.io source/images/originals/top-level-technical-diagram.drawio

Hasilkan versi SVG dari diagram dan simpan ke folder source/images/originals :

 draw.io -x -o source/images/top-level-technical-diagram.svg source/images/originals/top-level-technical-diagram.drawio

draw.io -x -o source/images/technical-flow-diagram.svg source/images/originals/technical-flow-diagram.drawio

Linting the gov.uk satu dokumentasi teknis login

Repositori ini menggunakan Vale dan aturan Linter GDS Tech Docs.

Memasang linter di mesin lokal Anda

Anda perlu:

• Pasang homebrew
• Instal Vale

Berbaris dengan editor kode Anda

Banyak editor kode menyediakan ekstensi atau plugin untuk Vale yang dapat meningkatkan kesalahan saat Anda memperbarui dokumentasi. Anda masih perlu Vale terpasang di mesin lokal Anda.

Berbaris dengan antarmuka baris perintah vale (CLI)

Secara default, Vale harus dijalankan dari direktori yang sama dengan file konfigurasi ini, kecuali -bendera --config disediakan dengan jalur. Untuk menjalankan linter menggunakan Vale Cli:

1. Di jendela terminal, navigasikan ke repo Anda.
2. Jalankan vale sync untuk mengunduh paket Tech-Docs-Linter terbaru dan unzip ini ke StylesPath Anda yang tercantum dalam file konfigurasi Anda.
3. Jalankan Command vale . untuk meletakkan seluruh repo atau menyediakan jalur ke direktori untuk hanya berbaris di direktori itu misalnya: vale ./source/go-live

Memperbarui ke aturan linter Docs Tech terbaru

Jika aturan baru ditambahkan ke aturan LINTER TECH Docs, Anda dapat meningkatkan paket yang digunakan oleh repo ini saat Anda siap. Versi aturan selanjutnya dapat diuji dan ditambahkan oleh:

1. Buat cabang.
2. Perbarui nomor versi paket dalam file konfigurasi Vale.
3. Jalankan vale sync untuk mengunduh dan unzip paket terbaru.
4. Jalankan vale ./source untuk menguji linter.
5. Perbaiki setiap perubahan aturan baru lemparan (lebih disukai satu komit untuk setiap pelanggaran aturan).
6. Naikkan PR dengan nomor versi terbaru dalam file Vale Config.

Kode Etik

Silakan merujuk ke Kode Etik alphagov .

Lisensi

Kecuali dinyatakan sebaliknya, basis kode dirilis di bawah lisensi MIT. Ini mencakup basis kode dan kode sampel apa pun dalam dokumentasi.

Dokumentasi adalah © Crown Copyright dan tersedia di bawah ketentuan Lisensi Pemerintah Terbuka 3.0.