Antares Programming Content Guidelines

Mga guideline sa pagsulat ng articles para sa Antares Programming

Note Isa itong work-in-progress document.

Ang pagsulat ang pangunahing paraan ng pagtuturo para sa Antares Programming. Para maging isang epektibong learning material ang mga sulatin at artikulong inilalabas ng Antares Programming, kailangang masiguro na ang mga ito ay (1) tumpak sa lahat ng nilalaman nito, (2) madaling maunawaan, at (3) accessible. Ina-outline ng dokumentong ito ang mga guidelines na dapat sundin sa pagsusulat para sa Antares Programming.

Mga Prinsipyo

Ang layunin ng pagsulat para sa Antares Programming ay ang makapag-produce ng de-kalidad na learning materials para sa lahat ng mga Pilipinong gustong matutong gumawa ng mga website. Para maabot ito, kailangang isaisip ang tatlong prinsipyong pi­nanghahawakan ng Antares Programming. Ang isang mahusay na sulating nakapagtuturo ay

• tumpak
• madaling maunawaan
• accessible

Nagiging mahusay at kapaki-pakinabang para sa lahat ng mambabasa kapag ang isang sulatin o artikulo ay nakaayon sa tatlong prinsipyong ito.

Maging accurate

Higit sa lahat ng iba pang characteristics ng isang de-kalidad na educational resource, pinakamahalaga ang accuracy ng impormasyong inilalaan nito. Kahit ma-achieve ng isang educational resource ang lahat ng iba pang characteristics na gusto nitong maabot, hindi ito magiging “educational” kung hindi ito tumpak. Kumukuha ang Antares Programming ng impormasyon mula sa mga mapagkakatiwalaang source. Para sa Web development, madaling i-verify ang impormasyon kung ite-test lang sa browser ang isang technology. Ang paggana ng technology o feature ay kumpirmasyon na ang source ay nagsasabi ng accurate na impormasyon. Sa Web development, ang W3C Specifications ang ultimate source of truth. Pero isa itong technical document tungkol sa mga features na dapat makita sa mga Web browser. Para sa source na mas simple at madaling unawain, ginagamit ng Antares Programming ang Mozilla Developer Network Documentations na ibinase mismo sa mga specifications.

Para naman sa mga impormasyon tungkol sa mga bagong framework, techniques, at paparating pa lang na technology, credible sources ang CSS Tricks, Smashing Magazine, at A List Apart. Nariyan din ang iba’t ibang personal blog mula sa mga developers. Kailanma’t ginagamit ang mga personal blog na ito sa mga articles ng Antares Programming, nakalagay ang link nila sa References section ng article.

Dalhin ang mambabasa sa iba pang references

Kapag nagsusulat, isaisip na hindi mo kayang ituro ang lahat ng konseptong kailangang maunawaaan ng mambabasa. Sikaping banggitin nang madalas ang mga reperensiyang pinagkuhaan mo at pasiglahin ang mambabasa na tumingin sa iba pang mga information resource para sa karagdagang detalye.

Madaling maintindihan

Ang isang educational resource ay madaling maintindihan ng kahit na sinong may sapat na prerequisite knowledge sa isang paksa. Malaking bahagi nito ang wikang ginagamit sa nasabing resource dahil wika ang nagsisilbing channel ng information papunta sa mag-aaral.

Sa bawat article, sinisikap ng Antares Programming na gumamit ng wikang madaling unawain. Kasama rito ang pagsusulat na parang personal na nakikipag-usap sa mambabasa. Kasama rin dito ang pagkakaroon ng definition sa lahat ng terminology na ginagamit sa isang article, regardless kung ang target audience ng article ay isang grupo na karaniwan nang may kaalaman tungkol sa topic—kailangang maunawaan din ito ng mga taong interesado pero hindi pamilyar dito.

Isaisip ang mambabasa

Kapag nagsusulat, huwag kalimutan ang target audience mo. Sa simula ng bawat artikulo, banggitin kaagad kung sino ang target auience, at ano ang mga konseptong kailangan muna nilang intindihin bago nila maunawaan ang impormasyong isinusulat mo.

Iwasan mong mag-assume na alam na ng target audience mo ang sinasabi mo. Kapag nagbanggit ka ng isang konsepto, salita, o teknolohiya sa mga sinusulat mo, ipaliwanag sa maikli kung ano iyon, at, kung hindi iyon ang paksa ng sinusulat mo, i-direct ang mga mambabasa sa ibang information resource na makakatulong sa kanila para maunawaan ang konseptong iyon.

Tandaan din na sa maraming kaso, posibleng alam na ng mga mambabasa mo kung ano ang konseptong tinutukoy mo, hindi nga lang nila alam kung ano ang tawag dito. Halimbawa, posibleng alam nila na tina-transform ng browser ang HTML para maging isang document tree na gagamitin ng JavaScript at CSS, hindi nga lang nila alam na Document Object Model (DOM) ang tawag doon. Puwedeng ma-confuse ang ilang mambabasa kapag ginamit mo ang DOM sa artikulo mo pero hindi mo nabanggit kung ano ito. Ang isang maikli at simpleng paliwanag kung ano ang isang konsepto ay malaking tulong na para sa mambabasa. Kung pamilyar sila rito, alam na nila kung ano ang sinasabi mo. Pero kung hindi, alam nila na kailangan nilang aralin ito sa ibang pagkakataon.

Paggamit ng wika

Filipino ang pangunahing wika ng Antares Programming. Pero hindi ibig sabihin nito na dapat maging pormal ang mga artikulo at sulatin para sa Antares Programming. Sikaping gumamit ng natural na wika, gaya ng ginagamit mo araw-araw.

Huwag pigilin ang sarili na gumamit ng Taglish, lalo na kung iyon ang gagamitin mo kapag nagsasalita ka at nakikipag-usap. Pero tandaan din na iba ang pagsasalita sa pagsusulat. Kapag gumagamit ng mga salitang Ingles, sikaping sundin ang mga tuntunin sa gramatika at masinop na pagsulat. Tingnan ang Ilang mga notes tungkol sa balarila.

Paggamit ng teknikal na Filipino

Patuloy ang development ng wikang Filipino. Sa mga nakalipas na taon, pinu-push ng mga awtoridad sa wikang Filipino na magamit din ang wikang pambansa sa mga propesyonal na setting. Kasama rito ang mga teknikal na industriya gaya ng software development.

Dahil dito, nakita natin ang paglitaw ng mga Filipino neologism, mga salitang inimbento para tumukoy sa mga bagong bagay. Halimbawa nito ang mga salitang gaya ng “pook-sapot” para sa “website”, “pantablay” para sa “charger”, at “panginain” para sa web browser. Kahit may magandang layunin, hindi dapat gamitin ang mga salitang ito sa mga artikulo ng Antares Programming. Dahil nga bago, hindi pa mauunawaan ng karamihan ang mga salitang ito. Para sa karamihan, maituturing ang mga salitang ito bilang mga jargon, mga salitang ginagamit lang sa mga espesipikong industriya.

Paggamit ng iba’t ibang media

Magiging mas madaling maunawaan ang mga konseptong isinusulat mo kung may kasama itong media content. Tingnan kung puwede mong samahan ng diagrams at images ang article mo. Tingnan din kung makikinabang ang mga mambabasa sa mga maiikling animations na nagde-demonstrate ng konsepto in action. Puwede ring magsama ng mga video o footage na nagpapakita ng konteksto ng paksang tinatalakay mo.

Pero dapat na kapaki-pakinabang pa rin ang artikulo mo kahit wala ang mga media content na ito. Dahil karamihan ng target audience ng Antares Programming ay nasa Pilipinas kung saan may mabagal na Internet connection, hindi laging makikita ng mga mambabasa ang mga media content na ito. Siguruhin na anoman ang media content na inilagay mo sa article mo, dapat na may mga text alternative ito, o kung hindi naman, dapat na makatatayong mag-isa ang isinulat mo kahit wala ang mga media content na ito.

Note Kapag magsasama ka ng media content sa article mo, tingnan ang content license para malaman mo kung puwede bang isama iyon. Lagi ring ilagay ang source ng media content. Mas maganda kung maglalagay ka ng link papunta sa source nito.

Pagiging Accessible

Kailangang maging accessible ang mga artikulo ng Antares Programming para sa lahat ng mambabasa nito. Kasama rito ang mga taong may problema sa paningin, pandinig, pagsasalita, at mga taong may learning disability. Para sa kanila, mahalaga na maging accessible ang mga binabasa nila.

Pagsusulat para sa mga may mababang reading comprehension

Mas mahirap ang pag-aaral ng mga techinical concepts para sa mga taong may mababang reading comprehension. At isa iyang malaking problema na dapat mong solusyunan bilang contributor para sa Antares Programming.

Sa pagsusulat, gumamit ng mga heading at subheading. Makatutulong ito para maging obvious ang outline at structure ng artikulo mo. Makakatulong ito sa mga mambabasa para makasabay sa train of thought na ine-establish mo sa artikulo mo.

Sikapin ding gawing maikli ang bawat paragraph ng sinusulat mo. Magiging mas madali itong basahin para sa lahat. Pero hindi ibig sabihin nito na kailangan mong piliting gawing maikli ang mga paragraph mo. Kung kinakailangang gumamit ka ng mas mahahabang pangungusap para maipaliwanag ang konseptong gusto mong itawid, gawin mo iyon. Huwag ipagpalit ang mahahalagang detalye para lang maging maikli ang mga pangungusap. Tingnan din kung aling pagkakasunod-sunod ng mga salita ang pinaka mabuti at pinaka madaling maunawaaan.

Sumulat nang nakaayon sa pagkakasunod-sunod, hindi sa posisyon

Sa ilang kaso, kailangan mong tumukoy ng mga larawan, diagram, at figure sa artikulo mo. Sa mga ganitong kaso, huwag gumamit ng mga positional na salita. Sa halip, gumamit ng mga absolute na pantukoy.

Halimbawa:

DI-DAPAT (Positional)

Para sa higit pang detalye, tingnan ang diagram sa kanan.

DAPAT (Chronological)

Para sa higit pang detalye, tingnan ang susunod na diagram

MAS MABUTI (Absolute)

Para sa higit pang detalye, tingnan ang diagram sa Figure 3.1.

Pagsusulat nang may device independence

Cross-platform ang Web. Gumagana ito sa lahat ng devices na may web browser. Kasama sa mga device na ito ang mga computer na may iba’t ibang input method. Maaring ang ilan ay may mouse, samantalang ang iba ay touch screen, at ang iba naman ay voice-controlled. Kaya naman sa pagsusulat, lalo na kung may kinalaman sa commands at actions sa mga user interface ang isinusulat mo, tiyakin na nagsusulat ka para sa lahat ng device, hindi lang para sa isa.

Halimbawa:

DI-DAPAT (Positional)

Para sa makapagbukas ng bagong file, i-click ang “Open existing file…”.

I-tap ang “Share” button, at sa lalabas na menu, i-tap ang “Copy Link”

DAPAT (Chronological)

Para sa makapagbukas ng bagong file, piliin ang “Open existing file…”.

Piliin ang “Share”, at sa lalabas na menu, piliin ang “Copy Link”.

Kapag ganito ang paraan natin ng pagsusulat, masisiguro natin na makakasunod ang mambabasa sa mga instruction na inilalagay natin sa mga article natin, anuman ang device na gamit nila.

Tinig at estilo ng pagsulat

Kapag nagsusulat para sa Antares Programming, isiping isa kang estudyanteng nagtuturo sa kapuwa niya mag-aaral. Ilagay ang sarili sa posisyon ang iyong kaklase sa konteksto ng isang paaralan.

Hindi sobrang pormal

Hindi ka naman gagamit ng pormal na Filipino kapag kausap mo ang mga kaklase mo, tama? Kaya hindi rin dapat maging napakapormal ng Filipinong ginagamit sa pagsusulat para sa Antares Programming.

Tandaan, gusto nating bawasan ang pagiging teknikal ng mga aralin sa web development. Kung gagamit tayo ng pormal na Filipino, magiging mas mahirap intindihin ang artikulo, at magiging lalong teknikal ang tono nito para sa mambabasa.

Mababaw pero may awtoridad

Sa pagsisikap na gawing mas impormal o mababaw ang Filipino sa pagsulat, kadalasan nang nababawasan ang awtoridad ng isinusulat mo. Narito ang ilan sa mga puwede mong gawin:

• Iwasang gumamit ng memes sa mga artikulo. Totoo, nakapupukaw ito ng atensyon, pero nababawasan nito ang awtoridad ng artikulo. At para sa ilang mga mambabasa na may kasanayan na tungkol sa paksa mo, isa itong cheap na paraan para maging interesting ang artikulo mo. Sikaping pukawin ang interes ng mambabasa gamit lang ang estilo mo ng pagsulat.
• Sundin ang mga tamang bantas. Gamitin nang tama ang mga tuldok, kuwit, tutuldok (colon), tuldok-kuwit (semi-colon), gatlang (dash), at iba pang mga bantas. Kahit mga estudyante ang target audience ng Antares Programminng, hindi maiiwasang magkaroon ng mga mambabasang nagmula sa iba’t ibang skills at fields. Magmumukhang professional ang artikulo mo kapag nakasunod ito sa tamang gamit ng mga bantas. Para sa higit pang detalye, tingnan ang Ilang notes tungkol sa balarila.
• Ayusin ang baybay ng mga salita. Dahil nga Filipino ang gamit nating wika, puwede mong isipin na kung ano ang bigkas, siyang baybay. Pero hindi ito totoo sa maraming kaso, lalo na kung isang lokal na wikang bukod sa Tagalog ang wikang sinasalita mo mula pa sa pagkabata. Kaya naman nagkakaroon tayo ng mga pagkakaiba sa pagbigkas, gaya sa salitang “propesyonal” at “propesyunal”; “anu-ano” at “ano-ano”; “puwede” at “pwede”; “buwaya” at “bwaya”; at marami pang iba. Sa ganitong mga kaso, sumangguni sa isang diksyunaryo bago gamitin ang isang salita. Pinaka katiwa-tiwala ang UP Diksyonaryo dahil itinuturing itong awtoridad pagdating sa wikang Filipino.

Structure ng mga artikulo

May sinusunod na structure ang mga artikulo sa Antares Programming, depende sa kung anong uri ito ng sulatin o kung ano ang paksang tinatalakay nito. Tandaan na ang mga ito ay suhestiyon lamang; kung kinakailangang lumihis sa mga ito ang sulatin o gumamit ng ibang structure, gawin mo iyon para sa kapakinabangan ng mambabasa.

Tutorial articles

Ang mga tutorial article ay mga sulating naglalayong magturo kung paano gagamitin ang isang konsepto o teknolohiya.

Pamagat

Para sa pamagat, sundin ang structure na ito:

Paggamit ng <teknolohiya o konsepto> para/para sa <layunin>

Halimbawa:

• Paggamit ng CSS clamp() para maging responsive ang font sizes mo
• Paggamit ng Jekyll para makabuo ng sarili mong blog

Tandaan na ang mga ito ay suggestion. Kung sa tingin mo ay mauunawaan ng mambabasa ang pamagat ng artikulo kahit lumihis nang kaunti sa suggestion na ito, puwede mong gawin iyon. Pero mas mainam na sundin ang mga ito para mas maunawaan ng mambabasa ang pamagat ng sulatin mo.

Outline

Karaniwan nang sinusunod ng mga tutorial article ang outline na ito:

1. Introduksyon (isa o dalawang parapo)
2. Prerequisites
3. Proseso
   1. Step 1 (hal., installation)
   2. Step 2
   3. Step N
4. Conclusion

Formatting

Code samples

Siguruhing magsama ng detalyadong code samples sa mga artikulo, lalo na para sa mga tutorial articles.

• Huwag gawing image ang mga code samples.
• Gumamit ng <pre></pre> at <code>&</code> tags.
• Para sa HTML code samples, siguruhing i-convert ang less-than symbol (<) patungo sa katumbas nitong HTML entity (<) para hindi malito ang browser sa mga HTML tag na nasa code samples mo.
• Para sa mga live code samples (mga code sample na may kasamang result), puwedeng gumamit ng mga code embedding service na gaya ng Codepen
• Para sa mas mahahabang code samples, huwag ilagay sa artikulo ang code. Sa halip, gamitin ang Github Gists para i-embed ang code sa artikulo.

Mga Pamagat at Subheading

Para sa mga pamagat at subheading, gumamit ng sentence case sa lahat ng pagkakataon.

DI-DAPAT (Title case)

Paggamit ng Jekyll Para sa Sarili Mong Blog

DAPAT (Sentence case)

Paggamit ng Jekyll para sa sarili mong blog

Ang site styling na ang bahalang bumago sa case ng mga pamagat kung kinakailangan.

Iba pang guidelines

Ilang mga notes tungkol sa balarila

Capitalization at spaces

Huwag i-capitalize ang mga salitang “internet”, “web”, “website”, at “web development”.

Dapat ding gamitin ang “website” sa halip na “web site” at “webpage” sa halip na “web page”.