Βικιπαίδεια:Τεκμηρίωση προτύπου

Τα πρότυπα είναι ένα πολύ ισχυρό χαρακτηριστικό του MediaWiki, αλλά μπορεί να προκαλέσει σύγχυση στους νέους χρήστες και ακόμη και οι έμπειροι χρήστες μπορεί να έχουν δυσκολία να καταλάβουν τα πιο περίπλοκα. Τα πρότυπα θα πρέπει επομένως να συνοδεύονται από τεκμηρίωση για τη βελτίωση της χρησιμότητας.

Η τεκμηρίωση του πρότυπου πρέπει να εξηγεί τι κάνει ένα πρότυπο και πώς χρησιμοποιείται. Θα πρέπει να είναι αρκετά απλή ώστε ένας χρήστης χωρίς πλήρη γνώση των περιπλοκών της σύνταξης του πρότυπου - που περιλαμβάνει πολλούς έμπειρους συνεισφέροντες που εστιάζουν την προσοχή τους αλλού - να μπορεί να το χρησιμοποιήσει σωστά. Αυτό ισχύει ιδιαίτερα για τα πολύ ευρέως χρησιμοποιούμενα πρότυπα.

Οι χρήστες θα πρέπει να συμμορφώνονται με τις επίσημες πολιτικές ή κατευθυντήριες γραμμές όταν οι σελίδες τεκμηρίωσης πρότυπου δεν είναι συμβατές με τις καθιερωμένες συμβάσεις και αρχές της κοινότητας. Οι συντάκτες θα πρέπει επίσης να αποφεύγουν την "παραπομπή" σελίδων τεκμηρίωσης προτύπων σαν να είναι πολιτική - συμπεριλαμβανομένου αυτού του οδηγού για το πώς να χρησιμοποιήσετε. Οι σελίδες τεκμηρίωσης προτύπων μπορούν να γραφτούν χωρίς μεγάλη - αν υπάρχει - συζήτηση, σε αντίθεση με τις πολιτικές της Βικιπαίδειας που έχουν ελεγχθεί διεξοδικά από την κοινότητα (βλ. Βικιπαίδεια:Συναίνεση#Επίπεδο συναίνεσης για λεπτομέρειες).

Τι πρέπει να περιλαμβάνεται

Η τεκμηρίωση του προτύπου πρέπει να καλύπτει:

• Ο βασικός σκοπός του προτύπου: τι κάνει και αν δεν είναι άμεσα προφανής, γιατί πρέπει να γίνει. Αν υπάρχουν άλλα πρότυπα με παρόμοια ονόματα ή σκοπούς, είναι καλή ιδέα να τα αναφέρουμε, προκειμένου να μειωθεί η πιθανότητα να χρησιμοποιηθεί το λάθος. Περιλάβετε σημαντικούς περιορισμοί, όπως η έλλειψη εμφάνισης των προτύπων πλοήγησης στον ιστότοπο για κινητά, αν ένα πρότυπο πρέπει να χρησιμοποιείται μόνο για ορισμένες χώρες ή χρονικές περιόδους, ή άλλα πράγματα που οι συντάκτες πρέπει να γνωρίζουν πριν επιλέξουν να χρησιμοποιήσουν το πρότυπο.
• Οι παράμετροι του προτύπου: αν είναι αριθμημένοι, ονομαστικοί ή προαιρετικοί, και αν ναι, ποιες είναι οι προεπιλεγμένες τιμές και ποια επίδραση έχουν. Εάν μια παράμετρος μπορεί να λαμβάνει μόνο ένα περιορισμένο σύνολο τιμών ή είναι περιορισμένη με οποιονδήποτε τρόπο, για παράδειγμα, αν μπορεί να χρησιμοποιεί μόνο "ναι", "όχι" ή έναν αριθμό, αυτό πρέπει να εξηγείται σαφώς.
• Παραδείγματα χρήσης: προσδιορίστε το ακριβές wikitext που πρέπει να χρησιμοποιηθεί και το αποτέλεσμα που παράγει. Το wikitext μπορεί να περιληφθεί σε ένα <code>...</code> πλαίσιο, για να είναι σαφές και εύκολο να αντιγραφεί, όπως αυτό. Εάν το πρότυπο μπορεί να χρησιμοποιηθεί με διάφορους τρόπους, με ή χωρίς προαιρετικές παραμέτρους, για παράδειγμα, να παρέχεται μια σειρά από παραδείγματα. Ένας καλός τρόπος για να γίνει αυτό είναι να ενσωματωθεί το πρότυπο στην ίδια την τεκμηρίωση μερικές φορές (δηλαδή, χρησιμοποιήστε ζωντανά παραδείγματα), με διαφορετικές παραμέτρους κάθε φορά και να απαριθμήσετε τις παραμέτρους που χρησιμοποιούνται σε κάθε περίπτωση.
• Στοιχεία TemplateData: Βλέπε Βικιπαίδεια:TemplateData.
• Σχετικά πρότυπα: αν το πρότυπο είναι ένα από μια σειρά προτύπων συμπεριλάβετε συνδέσμους προς αυτά - συγκεκριμένα εξασφαλίστε ότι κάθε πρότυπο της σειράς συνδέεται με κάθε ένα από τα άλλα, καθώς αυτό διευκολύνει τη πλοήγηση.   (Ένα ξεχωριστό πρότυπο πλοήγησης μπορεί να είναι χρήσιμο για αυτό το σκοπό).
• Κατηγορίες όπου είναι δυνατόν (διασυνδέσεις μεταξύ των Wikimedia πρέπει να παρατίθενται στο Wikidata - περισσότερες πληροφορίες στο Βικιπαίδεια:Wikidata). Στο πλαίσιο της τεκμηρίωσης, οι κατηγορίες πρέπει να καταχωρίζονται σε ετικέτα <noinclude>...</noinclude> σε ένα πρότυπο, ή σε ετικέτες <includeonly>{{Άλλο πρόχειρο||...}}</includeonly> αν τοποθετηθούν σε μια σελίδα τεκμηρίωσης. Πολλές κατηγορίες πρότυπων είναι διαθέσιμες, βλ.: Κατηγορία:Πρότυπα Βικιπαίδειας για να περιηγηθείτε μέσα από αυτές.

Πού να τοποθετηθεί;

Όταν βλέπετε την ίδια την σελίδα του προτύπου (σε αντίθεση με τον κώδικά του), αυτό που είναι συνήθως ορατό ακριβώς κάτω από τον τίτλο είναι το ίδιο το πρότυπο, ακολουθούμενο από μια ξεχωριστή ενότητα για να εμφανιστεί η τεκμηρίωση του προτύπου, ακολουθώντας τις κατηγορίες στις οποίες ανήκει το πρότυπο. Οι κατηγορίες και η τεκμηρίωση κάθε είδους σε μια σελίδα πρότυπου (συμπεριλαμβανομένων των TemplateData) πρέπει πάντα να συνοδεύονται από ετικέτες noinclude, ώστε να μην εμφανίζονται όταν το πρότυπο χρησιμοποιείται σε άλλη σελίδα.

Ο επεξεργαζόμενος κώδικας wiki για την τεκμηρίωση του πρότυπου τοποθετείται συχνά σε ξεχωριστή υποσελίδα του ίδιου του πρότυπου, η οποία ενσωματώνεται στη συνέχεια στο τέλος της σελίδας του πρότυπου. Αυτό διαχωρίζει τον συχνά περίπλοκο κώδικα πρότυπου από την τεκμηρίωση, διευκολύνοντας την επεξεργασία της τεκμηριώσεως και μειώνοντας τον αριθμό τυχαίων σφαλμάτων επεξεργασίας στον κώδικα του πρότυπου. Επιτρέπει επίσης να προστατεύονται τα πρότυπα όπου είναι απαραίτητο, περιορίζοντας την πρόσβαση στη επεξεργασία του κώδικα σημαντικών προτύπων, ενώ επιτρέπει σε οποιονδήποτε να επεξεργαστεί την τεκμηρίωση αυτών των προτύπων.

Πώς να δημιουργήσετε μια υποσέλιδα τεκμηρίωσης

Βάλτε τεκμηρίωση στο πρότυπο

Πρέπει να βάλετε {{documentation}} κατά τη δημιουργία (δημοσίευση) ενός πρότυπου. Στη συνέχεια δημιουργείται μια σελίδα τεκμηρίωσης με συνδέσμους [προβολή] [επεξεργασία] [ιστορικό] [ανανέωση]. Μπορείτε να δημιουργήσετε και να επεξεργαστείτε την τεκμηρίωση πρότυπου κάνοντας κλικ στο σύνδεσμο [επεξεργασία].

Οι υποσέλιδες προτύπου που χρησιμοποιούν {{documentation}} ονομάζονται και μορφοποιούνται χρησιμοποιώντας το ακόλουθο γενικό πρότυπο, για συνέπεια.

Ας υποθέσουμε ότι το πρότυπο σας ονομάζεται Πρότυπο:X. Τροποποιήστε το πρότυπο και προσθέστε το ακόλουθο στο τέλος του κώδικα πρότυπου:

[--τελευταία γραμμή του κώδικα του προτύπου --]<noinclude>
{{Documentation}}
<!-- Προσθέστε κατηγορίες στην υποσελίδα /τεκμηρίωση και interwiki στα Wikidata, όχι εδώ! -->
</noinclude>

Αυτό θα ενσωματώσει το {{documentation}} στο κάτω μέρος της σελίδας πρότυπου.

Σημαντικό: Βεβαιωθείτε ότι το άνοιγμα <noinclude> αρχίζει αμέσως μετά το τελευταίο χαρακτήρα του κώδικα ή του κειμένου του πρότυπου και όχι σε μια νέα γραμμή, ούτε με οποιαδήποτε ενδιάμεσα κενά. Διαφορετικά, θα εισαχθεί επιπλέον χώρος κάτω από το πρότυπο όταν χρησιμοποιείται, το οποίο συνήθως δεν είναι επιθυμητό.

Εάν το πρότυπο είναι ήδη προστατευμένο, ζητήστε από έναν διαχειριστή να το κάνει αυτό ή ζητήστε μια τροποποίηση χρησιμοποιώντας {{editprotected}} στη σελίδα συζήτησης του προτύπου. Εάν η τεκμηρίωση και οι κατηγορίες υπάρχουν ήδη σε μια ενότητα, που περικλείεται σε ένα κοντέινερ <noinclude>...</noinclude>, μετακινήστε τα στην υποσελίδα τεκμηρίωσης (όπου θα πρέπει να εσωκλείονται στο <includeonly>...</includeonly> ), καθώς είναι καλύτερο να μην χωρίζεται η τεκμηρίωση σε δύο ξεχωριστές σελίδες.

Αυτόματη δημιουργία

Χρησιμοποιήστε τον σύνδεσμο [δημιουργία] στο κάτω μέρος του κενού πλαισίου τεκμηρίωσης για να δημιουργήσετε αυτόματα μια προφορτωμένη υποσελίδα τεκμηρίωσης. Εισαγάγετε την τεκμηρίωση μετά την επάνω γραμμή και τις κατηγορίες κάτω από την κατάλληλη γραμμή σχολίων – αφήνοντας το σχόλιο στη θέση του, έτσι ώστε η διάταξη να διατηρείται κατά την επεξεργασία της σελίδας στο μέλλον. Μπορείτε να συνδέσετε σχετικά πρότυπα, σελίδα πολιτικής, έργα κ.λπ. προσθέτοντας μια ενότητα "Δείτε επίσης". Αποθηκεύστε την υποσελίδα.

Χειροκίνητη δημιουργία

Για να δημιουργήσετε την υποσελίδα τεκμηρίωσης με μη αυτόματο τρόπο, δημιουργήστε μια υποσελίδα με το όνομα Template:X/τεκμηρίωση. Δείτε τις λεπτομέρειες στη {{Υποσελίδα τεκμηρίωσης}} ή ξεκινήστε τη σελίδα επικολλώντας το ακόλουθο τυπικό wikitext:

{{Υποσελίδα τεκμηρίωσης}}
== Χρήση ==


<includeonly>{{Sandbox other||
<!-- Κατηγορίες κάτω από αυτή τη γραμμή -->

}}</includeonly>

Η επάνω γραμμή θα εμφανίσει ένα μήνυμα που εξηγεί την τρέχουσα σελίδα και έναν σύνδεσμο προς τη σελίδα προτύπου. Αποθηκεύστε την υποσελίδα και ακολουθήστε τις οδηγίες στην ενότητα " Χρήση προτύπου:Τεκμηρίωση ".

Κατηγορίες και σύνδεσμοι interwiki

• Για να τοποθετήσετε το ίδιο το πρότυπο σε μια κατηγορία, προσθέστε τον κωδικό [[Κατηγορία:Όνομα κατηγορίας]] μέσα σε μια ενότητα <includeonly>...</includeonly> στην υποσελίδα τεκμηρίωση.
• Για να δημιουργήσετε έναν σύνδεσμο interwiki για το ίδιο το πρότυπο, μεταβείτε στα Wikidata και ακολουθήστε τις οδηγίες για την προσθήκη συνδέσμων σε σελίδες.
• Για να τοποθετήσετε την υποσελίδα τεκμηρίωση σε μια κατηγορία, προσθέστε τον κώδικα [[Κατηγορία:Όνομα κατηγορίας]] μέσα σε μια ενότητα <noinclude>...</noinclude> στην υποσελίδα τεκμηρίωση .
• Για να κάνετε το πρότυπο να τοποθετεί ένα λήμμα σε μια κατηγορία (όταν το λήμμα περιλαμβάνει το πρότυπο), προσθέστε τον κωδικό [[Κατηγορία:Όνομα κατηγορίας]] μέσα σε μια ενότητα <includeonly>...</includeonly> στη σελίδα προτύπου. Η ακριβής τοποθέτηση εντός του κώδικα του προτύπου μπορεί να επηρεάσει τον τρόπο εκτέλεσης του κώδικα κατηγορίας.

/πρόχειρο και /testcases

Πριν κάνετε αλλαγές σε ένα πρότυπο, μπορεί να είναι καλό να αντιγράψετε πρώτα τον κώδικα του προτύπου σε ένα πρόχειρο και να εκτελέσετε ορισμένες δοκιμαστικές περιπτώσεις, καθώς το πρότυπο μπορεί να είναι ορατό σε χιλιάδες ή και εκατομμύρια σελίδες. Εάν δημιουργήσετε υποσελίδες με το όνομα «/πρόχειρο» και «/testcases» σε ένα πρότυπο, τότε το πράσινο πλαίσιο {{documentation}} στο πρότυπο το εντοπίζει αυτόματα και θα εμφανίζει συνδέσμους προς αυτές τις σελίδες στην κεφαλίδα του.

Πολλά πρότυπα, μία σελίδα τεκμηρίωσης

Όταν πολλά πρότυπα συνεργάζονται ή είναι πολύ παρόμοια, τότε είναι συχνά πιο σαφές και ευκολότερο να διατηρηθεί μια ενιαία σελίδα τεκμηρίωσης που τα τεκμηριώνει μαζί. Ο απλούστερος τρόπος για να το κάνετε αυτό είναι να δημιουργήσετε μια πλήρη σελίδα τεκμηρίωσης σε ένα από τα πρότυπα και, στη συνέχεια, να κάνετε «μαλακές ανακατευθύνσεις»¬ από τα άλλα πρότυπα. Δείτε, για παράδειγμα: {{wrap}}.

Απευθείας σε μια σελίδα προτύπου

Όταν δεν έχει δημιουργηθεί μια υποσελίδα τεκμηρίωσης και το πρότυπο {{documentation}} χρησιμοποιείται με παράμετρο |content= στην πραγματική σελίδα προτύπου, τότε για να τοποθετήσετε το ίδιο το πρότυπο σε μια κατηγορία, προσθέστε [[Κατηγορία:Όνομα κατηγορίας]] μέσα στο πρότυπο τεκμηρίωσης, μετά το περιεχόμενο. Για παράδειγμα, για τοποθέτηση στην πραγματική σελίδα προτύπου:

[--τελευταία γραμμή του κώδικα του προτύπου --]<noinclude>
{{Documentation
 | content =
<!-- τεκμηρίωση του προτύπου -->

[[Κατηγορία:Όνομα κατηγορίας]]
[[Κατηγορία:Όνομα κατηγορίας 2]]
}}</noinclude>

Όταν δεν απαιτείται τεκμηρίωση

Όταν ένα πρότυπο όπως εμφανίζεται θα συνδεθεί με μια σελίδα που μπορεί να χρησιμεύσει ως τεκμηρίωση, τότε η ξεχωριστή τεκμηρίωση είναι περιττή και δεν χρειάζεται να δημιουργηθεί. Για παράδειγμα, ένα πρότυπο «προς επέκταση», χρησιμοποιώντας το πρότυπο {{asbox}} ως βάση, θα εμφανίζει ήδη προφορτωμένη κοινή τεκμηρίωση για όλα τα πρότυπα «προς επέκταση» που χρησιμοποιούν αυτό το πρότυπο και δεν θα χρειάζεται πρόσθετη τεκμηρίωση.

Δείτε επίσης

• {{Documentation}} – Ενσωματώνει την τεκμηρίωση στη σελίδα προτύπου και παρέχει συνδέσμους προβολής, επεξεργασίας και ιστορικού τεκμηρίωσης
• {{Υποσελίδα τεκμηρίωσης}} – Εξηγεί ότι αυτό που ακολουθεί είναι τεκμηρίωση και συνδέει προς την τεκμηριούμενη σελίδα
• <noinclude> και<includeonly>