15. Ysgrifennu Meddalwedd

Mae gwahaniaeth rhwng ysgrifennu cod, neu rhaglen, ac ysgrifennu meddalwedd.

• Y cod, neu’r rhaglen, yw’r sgript mae’r cyfrifiadur yn trosglwyddo i mewn i cyfarwyddiadau.
• Meddalwedd yw’r pecyn cyfan a ddefnyddir gan pobl. Mae meddalwedd yn cynnwys cod, yn osgystal â ddogfennaeth, cyfarwyddiadau gosod, meta-data, a’r holl pethau eraill sy’n gwneud y cod yn hawdd i’w ddefnyddio.

Dylai meddalwedd cynnwys:

• Y cod, wedi lapio mewn ffordd sy’n hawdd cael gafael arno, ac sy’n hawdd i’w osod;
• Cyfarwyddiadau gosod;
• Dogfennaeth ar sut i’w ddenfyddio;
• Meta-data megis trwyddedau, cyfarwyddiadau ar sut i cyfeirio at y meddalwedd, a gwybodaeth fersiynnau.

Fel rhan i’r peth a elwir yn ‘meddalwedd’, fel arfer bydd cymuned o ddefnyddwyr a ddatbygwyr, a ffordd o ddenu ddefnyddwyr eraill megis cyhoeddiadau, wefan, a phresenoldeb ar y cyfryngau cymdeithasol.

Mae ysgrifennu meddalwedd yn hytrach na cod yn cynyddu ailgynhyrchadwyedd y gwaith a ddefnyddir, oherwydd bod meddalwedd yn haws cael gafael arno, haws deall sut i’w ddefnyddio, ac haws cael gwybodaeth fersynnau a cyfeirio, na sgriptiau unigol. Felly, wrth ysgrifennu meddalwedd rhaid meddwl a sicrhai ein bod yn ei ysgrifennu mewn ffordd sy’n galluogi ein defnyddwyr gwneud ymchwil ailgynhyrchiadwy.

Dogfennaeth Meddalwedd

• Mae angen i ddefnyddwyr gwybod sut i ddefnyddio’ch meddalwedd.
• Ysgrifennir dogfennaeth meddalwedd ar gyfer pobl. Mae’n esbonio sut i ddefnyddio’r meddalwedd, yn hytrach na sut mae’n gweithio.
• Wefan a gwasanaeth sy’n gwesteia dogfennaeth meddalwedd ffynhonell-agored am ddim yw ReadTheDocs. Mae’n defnyddio Sphinx i drawsnewid ffeiliau markdown neu .rst (sy’n hawdd i’w ysgrifennu) i fewn i html (sy’n hawdd i’w ddarllen).
• Mae nifer o ffyrdd i ysgrifennu a strwythuro dogfennaeth meddalwedd. Mae’r cofnod blog yma yn awgrymu un ffordd, sy’n gwahaniaethu rhwng tiwtorialau, canllawiau, esboniadau, a chyfeiriadau. Y peth pwysicaf yw i sicrhai bod eich darllenwyr yn gallu defnyddio’r meddalwedd ac yn cyfforddus gyda’r meddalwedd.
• Rhai enhreifftiau o ddogfennaeth meddalwedd:
  • Django
  • Ciw
  • Hypothesis
  • ReadTheDocs

Cyhoeddi Meddalwedd

• Mae angen i ddefnyddwyr gwybod am eich meddalwedd, a gallu ymddired yn eich meddalwedd.
• Nes y bydd newid mawr yn y ffordd rhoddir credyd academaidd, y prif modd o recordio, cyfarthrebu, ac ymddiried mewn ymchwil yw’r cyfnodolion academaidd. Mae modd cyhoeddi meddalwedd, neu papurau sy’n disgrifo â hysbysebu §meddalweddau, mewn cyfnodolion academaidd parchus. Mae’r cyhoeddiadau yma yn sicrhai credyd academaidd i’r datblygwyr, a yn rhoi hean o ymddiriedolaeth i’r meddalwedd.
• Dyma rhestr anghyflawn o gyfnodolion sy’n cyhoeddi papurau ar meddalwedd. Serch hyn, fe fydd rhai cyfnodolion pwnc-arbennigol ni rhestrir fan hyn hefyd yn cyhoeddi papurau sy’n disgrifio meddalwedd, o achos y symudiad i trîn meddalwedd fel allbwn ymchwil ar lefel hafal i ganlyniadau.

Yn y gwersi nesa, canolbwyntiwn yn fwy manwl ar meta-data meddalwedd: beth i cynnwys helpu defnyddwyr cyfeirio at y meddalwedd, cael gwbodaeth fersiynnau, a trwyddedau meddalwedd.