Inspired by SemVer, tailored for clear and concise document management in Markdown format.
The inception of Document Semantic was driven by the need to maintain effective document control within GIT, specifically for Markdown files. While GIT is adept at tracking code changes, traditional document formats aren’t always suitable for text-based diffing. Markdown, being text-based, integrates seamlessly with GIT, allowing for precise tracking of changes. The introduction of concise short codes ensures that document updates are both meaningful and GIT-friendly. While GIT and Markdown were the primary motivations, this approach is versatile and can benefit a range of documentation use cases.
New Document (ND)
Indicates that the document is newly created and has not been subject to any updates or changes.
Significant changes that might confuse readers familiar with a previous version.
Stable Release (IR)
Indicate that the document has reached a stable point and should be marked as version 1.0.0.
Content Change (CC)
Major changes to the document’s core content fall under this category. This could include altering key arguments, revising primary objectives, or modifying the main outcomes. Such changes can redefine the document’s purpose, narrative, or message, thereby requiring readers to essentially re-learn the content.
Structure Change (SC)
This involves a drastic rearrangement of the document’s existing layout or structure. Sections may be added, removed, merged, or split. The hierarchical levels of the content might also be changed. These changes can disrupt the flow and order of information, making it harder for readers familiar with the previous version to navigate the document easily.
Format Change (FC)
Major alterations to the document’s visual and presentation aspects fall here. This could involve changing the document type (e.g., from PDF to slideshow), adding multimedia elements, or a complete design overhaul. Such changes significantly alter the way the document looks or is interacted with, potentially requiring the reader to adapt to a new format.
Additions or updates that don’t modify the core content but enhance its comprehensiveness.
New Content (NC)
New sections or sub-sections added to the existing document fall under this category. Such additions provide supplementary information but do not alter the existing message, structure, or layout in a significant way. They are designed to enhance, not disrupt.
Clarity and Enhancement (CE)
This involves slight structural adjustments, sentence rephrasing, or adding explanations that make the document clearer and easier to understand. These are refinements that enhance the document without changing its core message or structure.
Corrections and enhancements that focus on refining the document’s quality.
Text Fixes (TF)
Minor spelling, grammar, or punctuation errors are corrected under this category. Such changes do not affect the document’s core content, layout, or meaning but improve its overall readability and professionalism.
Data and Link Fixes (DF)
This involves minor adjustments like fixing broken hyperlinks, updating outdated footnotes or references, and correcting inaccuracies in data tables or charts. These changes aim to enhance the credibility and reliability of the document without making major alterations.
The short codes, concise in nature, capture the essence of each change, simplifying communication about document updates. Adopting a standardized semantic system for documents ensures clarity, efficiency, and collaboration.