Σύστημα τεκμηρίωσης

Αρχιτεκτονική Συστήματος¶

Η γενική ιδέα

Επισκόπηση της αρχιτεκτονικής

Εδώ είναι μια γραφική αναπαράσταση της αρχιτεκτονικής του συστήματος:

flowchart LR
A(Περιεχόμενα) --> B(Έλεγχος εκδόσεων)
C(Λογισμικό επεξεργασίας) --> A
A --> D(Διαθέσιμο στο διαδίκτυο)

Αναλυτικά:

Επισκόπηση της αρχιτεκτονικής

flowchart LR
A[Obsidian] <--> B{Αρχεία}
B <--> C(Github Desktop)
C <--> D{Github}
B <--> E(MkDocs)
D --> F(Github Pages)
G(Θέμα: MkDocs-Material) --> E
H(MkDocs-Publisher) --> E
E --> D

Obsidian: Ένας προαιρετικός, αλλά από εμένα προτεινόμενος επεξεργαστής κειμένου για την επεξεργασία αρχείων Markdown.
Αρχεία: Τα αρχεία Markdown που περιέχουν το περιεχόμενο της τεκμηρίωσής μου.
Github Desktop: Ένα εργαλείο για την εύκολη διαχείριση των αποθετηρίων μου Git.
Github: Μια διαδικτυακή υπηρεσία για τον έλεγχο εκδόσεων και τη συνεργασία.
Github Pages: Μια δωρεάν υπηρεσία για τη δημοσίευση της ιστοσελίδας μου.
MkDocs: Ένα εργαλείο για την αυτόματη δημιουργία της ιστοσελίδας από τα αρχεία Markdown μου.
MkDocs-Material: Ένα θέμα για το MkDocs που προσφέρει μια μοντέρνα και ελκυστική διάταξη.
MkDocs-Publisher: Μια συλλογή από plugins που διευκολύνουν τη συνεργασία με το Obsidian και προσφέρουν επιπλέον λειτουργικότητα.

Συστατικά αναλυτικά¶

1. Markdown¶

Markdown ως βάση

Χρησιμοποιώ τη μορφή Markdown για την τεκμηρίωσή μου. Το Markdown είναι μια απλή γλώσσα σήμανσης που μου επιτρέπει να μορφοποιώ κείμενο με απλές μορφοποιήσεις (π.χ. επικεφαλίδες, λίστες, συνδέσμους).

Πλεονεκτήματα:

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

Markdown

2. Obsidian¶

Obsidian ως επεξεργαστής κειμένου

Το Obsidian είναι ένας προαιρετικός, αλλά από εμένα προτεινόμενος επεξεργαστής κειμένου. Μου προσφέρει τα ακόλουθα πλεονεκτήματα:

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

3. Git και Github¶

Git για έλεγχο εκδόσεων

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

Πλεονεκτήματα:

Έλεγχος εκδόσεων: Κάθε αλλαγή τεκμηριώνεται και μπορεί να ανακληθεί ανά πάσα στιγμή, κάτι που με βοηθά να αποφεύγω λάθη και να διατηρώ την επισκόπηση.
Συνεργασία: Πολλοί άνθρωποι μπορούν να εργάζονται ταυτόχρονα στην τεκμηρίωση, δίνοντάς μου τη δυνατότητα να ενσωματώνω σχόλια και συνεισφορές από άλλους.
Αντίγραφο ασφαλείας: Η τεκμηρίωσή μου είναι ασφαλής και δημιουργείται τακτικά αντίγραφο ασφαλείας, δίνοντάς μου τη βεβαιότητα ότι η εργασία μου δεν θα χαθεί.

4. Github Desktop¶

Github Desktop ως εργαλείο

Το Github Desktop είναι ένα γραφικό περιβάλλον για το Git, που μου επιτρέπει να χρησιμοποιώ το Git εύκολα και χωρίς γραμμή εντολών.

Πλεονεκτήματα:

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

5. MkDocs¶

MkDocs ως γεννήτρια ιστοσελίδων

Το MkDocs είναι μια στατική γεννήτρια ιστοσελίδων που μετατρέπει τα αρχεία Markdown μου σε μια στατική ιστοσελίδα.

Πλεονεκτήματα:

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

6. Github Pages¶

Github Pages για φιλοξενία

Το Github Pages είναι μια δωρεάν υπηρεσία φιλοξενίας από το Github, που μου επιτρέπει να δημοσιεύω εύκολα την ιστοσελίδα μου στο διαδίκτυο.

Πλεονεκτήματα:

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

7. MkDocs-Material¶

MkDocs-Material ως θέμα

Το MkDocs-Material είναι ένα θέμα για το MkDocs που προσφέρει μια μοντέρνα και ελκυστική διάταξη.

Πλεονεκτήματα:

Μοντέρνος σχεδιασμός, κάνοντας την τεκμηρίωσή μου να φαίνεται επαγγελματική και σύγχρονη.
Προσαρμόσιμο, επιτρέποντάς μου να προσαρμόζω τη διάταξη στις συγκεκριμένες ανάγκες μου.
Φιλικό προς τον χρήστη, διευκολύνοντας τη χρήση της τεκμηρίωσης.

8. MkDocs-Publisher¶

MkDocs-Publisher ως συλλογή plugins

Το MkDocs-Publisher είναι μια συλλογή από plugins του MkDocs που απλοποιούν τη συνεργασία με το Obsidian και προσφέρουν επιπλέον λειτουργίες.

Πλεονεκτήματα:

Απλοποιημένη ενσωμάτωση Obsidian: Αυτόματη προσαρμογή της σύνταξης Markdown του Obsidian (Callouts, Wikilinks κ.λπ.).
Επεκταμένα μεταδεδομένα: Ενσωμάτωση ετικετών και κατηγοριών από το frontmatter του Obsidian.

Ροή εργασίας¶

Η ροή εργασίας μου

Εδώ είναι η τυπική ροή εργασίας μου:

Δημιουργώ και επεξεργάζομαι αρχεία Markdown με έναν επεξεργαστή κειμένου (προαιρετικά Obsidian).
Αποθηκεύω τα αρχεία Markdown τοπικά.
Μεταφέρω τις αλλαγές μου στο αποθετήριο Git χρησιμοποιώντας το Github Desktop.
Δημιουργώ αυτόματα την ιστοσελίδα με το MkDocs.
Δημοσιεύω την ιστοσελίδα με το Github Pages.

Σύστημα αρχείων¶

Δομή καταλόγων

Εδώ είναι η δομή καταλόγων του συστήματός μου:

/docs/     (Εδώ βρίσκονται τα αρχεία Markdown μου)
/site/     (Εδώ δημιουργείται η ιστοσελίδα)
license    (Πληροφορίες άδειας χρήσης)
mkdocs.yml (Αρχείο διαμόρφωσης για το MkDocs)
readme.md  (Αρχείο για την περιγραφή του αποθετηρίου)

Εναλλακτικές για τη δημιουργία περιεχομένου¶

Εναλλακτικές για τη δημιουργία περιεχομένου

Γνωρίζω ότι δεν είναι όλοι εξοικειωμένοι με το Markdown και το Git. Γι' αυτό προσφέρω τις ακόλουθες εναλλακτικές:

Wordpress: Το περιεχόμενο μπορεί να δημιουργηθεί στο Wordpress ως σελίδα.
Αρχείο κειμένου, αρχείο Word: Το περιεχόμενο μπορεί να δημιουργηθεί ως αρχείο κειμένου, αρχείο Word (ή σε άλλες τυπικές μορφές).

Σε αυτές τις περιπτώσεις, μπορώ να ενσωματώσω το περιεχόμενο στο σύστημα.