Pecan: Garis Besar Dokumentasi

@robkooper dan @ashiklom Mencoba menggabungkan dua ide garis besar Anda. @KristinaRiemer dan @bailsofhay akan senang mendapatkan umpan balik Anda. Akan segera mulai menerapkan ini sehingga kami dapat memindahkan halaman ke tempat yang kami inginkan sebelum akhir bulan.

Saya pikir ini terlihat sangat bagus. Ini hanya menata ulang materi yang ada, tidak menambahkan apa-apa?

Ketika Anda melakukan ini, bab 41 harus benar-benar pergi sebelum 40.

@KristinaRiemer Ya, saya hanya akan memindahkan barang-barang. Sementara itu kami dapat mengidentifikasi hal-hal yang hilang dan membuat masalah. Perhatikan bahwa ini diberi label sebagai masalah "Epik" sehingga masalah lain ini dapat ditautkan di bawah Masalah ini sehingga kami dapat tetap teratur.

Saya hanya melihat-lihat dokumentasi untuk beberapa istilah untuk digunakan dalam penulisan cepat tentang apa yang saya lakukan. Saya menyadari bahwa doc tidak memiliki penjelasan terbaik mengapa seseorang ingin menggunakan pecan (khususnya tidak ada penjelasan untuk analisis ketidakpastian). Ini masuk akal untuk dimasukkan ke dalam bagian "Ikhtisar Proyek" dari dokumen yang tersedia saat ini, tidak yakin tentang di mana menambahkan ini untuk dokumen yang sedang kami kerjakan.

Tautan dari @infotroph tentang dokumentasi: https://www.divio.com/blog/documentation/

Tautan dari @infotroph tentang dokumentasi: https://www.divio.com/blog/documentation/

Lebih banyak konteks: Bagian ini membuat argumen yang kuat bahwa ada empat jenis dokumentasi perangkat lunak yang berbeda, dan bahwa semua proyek yang terdokumentasi dengan baik harus memiliki keempatnya sebagai bagian yang terpisah secara eksplisit:

• tutorial , untuk mengajari pemula apa yang dilakukan alat Anda menggunakan contoh langkah demi langkah yang dijamin berfungsi persis seperti yang dijelaskan setiap saat
• how-tos , bagian buku masak tempat pengguna dapat menjawab pertanyaan dalam formulir "Bagaimana caranya....?", yang hanya berisi detail yang mereka butuhkan untuk pertanyaan yang diberikan
• referensi , untuk detail halaman manual tentang cara memanggil sesuatu, protokol apa yang mereka gunakan, dan nilai apa yang mereka kembalikan
• diskusi , di mana Anda menjelaskan mengapa segala sesuatunya berjalan sebagaimana mestinya, memberikan informasi latar belakang, memberi nasihat tentang praktik baik vs buruk, dan sebaliknya memberikan konteks yang tidak sesuai dengan bagian lain.

Masalah ini sudah basi karena telah dibuka selama 365 hari tanpa aktivitas.

Untuk jangka panjang, saya pikir konsep tutorial/cara/referensi itu solid dan kami masih dapat mengklarifikasi dokumen dengan menerapkannya secara lebih seragam. Tetapi reorg yang awalnya dibahas di sini telah diterapkan sepenuhnya sehingga saya akan menutup masalah ini dan mendorong utas baru untuk pembersihan lebih lanjut.