Wikipedia:Dokumentacioni i stampës

Nga Wikipedia, enciklopedia e lirë

Stampat janë një tipar i fuqishëm i Mediawiki-it, por mund të mos kuptohen nga përdoruesit e rinj madje edhe përdoruesit me përvojë mund të kenë vështirësi në kuptimin e stampave komplekse. Si rrjedhojë stampat duhet të shoqërohen me një dokumentacion në mënyrë që të lehtësohet përdorimi i tyre.

Dokumentacioni duhet të shpjegojë se çfarë mund të kryejë një stampë dhe si mund të përdoret. Duhet të jetë i thjeshtë në mënyrë që edhe një përdorues pa njohuri të përgjithshme në sintaksën e stampave të mundet ta përdorë. Në këtë mënyrë koha që do të nevojitej në kuptimin e stampës mund të shfrytëzohet diku tjetër. Kjo është veçanërisht e vërtetë për stampat që përdoren gjerësisht.

Ç'duhet të përmbajë dokumentacioni[Redakto nëpërmjet kodit]

Dokumentacioni i stampës duhet të mbulojë:

  • Qëllimi themelor i stampës: atë që bën dhe nëse nuk është menjëherë e qartë, përse duhet të bëhet. Nëse ka stampa të tjera me emra ose qëllime të ngjashme, është ide e mirë t'i përmendni ato, në mënyrë që të reduktuar mundësinë e një përdorimi të gabuar.
  • Parametrat e stampës: nëse parametrat janë të numëruar, të emërtuar ose opsionalë, dhe nëse po, cilat janë vlerat standarte dhe çfarë efekti kanë ato. Nëse një parametër mund të marrë vetëm një grup të kufizuar të vlerave ose është i kufizuar në ndonjë mënyrë, për shembull, nëse ai mund të përdorë vetëm: "Po", "jo" ose një numër, kjo duhet të shpjegohet qartë.
  • Shembuj përdorimi: të specifikojë wikitekstin e saktë që duhet të përdoret dhe rezultati që ky wikitekst krijon. Wikiteksti mund të jetë i mbyllur në etiketat <code>…</code>, për ta bërë të qartë dhe të lehtë për tu kopjuar, si kjo. Nëse stampa mund të përdoret në mënyra të ndryshme, me ose pa parametra opsional, të sigurojë një sërë shembujsh. Një mënyrë e mirë për ta bërë këtë është që të përfshihet vetë stampa në dokumentacionin e disa herë (p.sh., përdorimi në shembuj realë), me parametra të ndryshme çdo herë dhe listën e parametrave të përdorur në çdo rast.