Share
In de wereld van CSS wordt documentatie te weinig gebruikt. Omdat documentatie niet zichtbaar is voor de eindgebruiker, wordt de waarde ervan vaak over het hoofd gezien door klanten. En als het je eerste documentatiedocatie is, kan het moeilijk zijn om te bepalen wat documenteren en hoe om het het meest effectief te doen.
Toch kan het documenteren van CSS veel toevoegen aan uw project: van het aanmoedigen van betere codepraktijken tot het vergemakkelijken van het aan boord gaan van nieuwe teamleden. In dit artikel zal ik de voordelen van het documenteren van CSS uitleggen en delen wat mijn team en ik bij Bitovi beschouwen als de beste werkwijzen om documentatie voor u te laten werken - en niet andersom. Laten we erin duiken.
Het is moeilijk om op de documentatie te geraken wanneer het voor u en uw team niet duidelijk is wat u moet documenteren of hoe u wilt dat het werkt. Dus de eerste stap is om overeenstemming te bereiken over welke conventies u zult gebruiken en hoe u ze moet implementeren. U kunt dit doen in een live document zodat iedereen in het team een bijdrage kan leveren. Op deze manier kunt u het up-to-date houden wanneer uw aanpak verandert of uitgebreid wordt. Een gedeeld Google-document, een wiki-pagina in uw code-repo of (nog beter) een pagina in uw "gids voor woonstijlen" zijn allemaal geweldige plaatsen voor dit.
Laten we nu kijken naar de feitelijke "basisregels" die u kunt opnemen.
Als u begrijpt hoe uw code is georganiseerd, kan iedereen vanaf de eerste dag meteen in de actie springen. Een eenvoudige manier om dit te doen is een kaart maken van uw bestandsstructuur waarin u kunt uitleggen wat erin zit en wat er moet gaan. Let daarbij bij voorkeur op die plaatsen waar onduidelijkheid kan bestaan. Bijvoorbeeld: aangeven dat het bestand "buttons.css" stijlen voor knoppen bevat, is niet erg nuttig, maar geeft aan dat de "aangepaste" map is waar aangepaste stijlen voor het thema zich bevinden, kan een tijdbesparing zijn.
Hier is een voorbeeld:
Project Root └── srs ├── stijlen // Basistijlen. Stijlen die hier worden geplaatst, moeten overal in de applicatie beschikbaar zijn ├── bootstrap-custom // Aangepaste stijlen die bootstrap overschrijven ├── aangepast // Aangepaste stijlen gemaakt voor de toepassing ├── demo's // Demo's om stijlen en interacties voor de stijl te illustreren gids ├── fonts ├── img // ALLEEN gebruikte afbeeldingen in stylesheets ├── variabelen // Variabelen gebruikt in het aangepaste thema └── styles.less // Import van alle basis stylesheets └── componenten ├── waarschuwingen └── alert.less // Aangepaste stijlen voor de waarschuwingscomponent. Elk onderdeel heeft een eigen stylesheet die het mogelijk maakt om het specifiek aan te passen om te voorkomen dat de bloat en de stijl lekken.
Als vuistregel documenteer die plaatsen waar verduidelijking nodig is. Niet elke directory en elk bestand zullen documentatie nodig hebben (zoals in het bovenstaande voorbeeld "fonts" spreken voor zich). Zet jezelf in de schoenen van iemand die nieuw is in het project (of onthoud die momenten waarin jij die persoon was) en geef de richtlijnen die je zou willen dat je zou krijgen. Het idee is om dit te doen op een manier die niet tijdrovend is voor u, maar voldoende nuttig is om herhalende vragen te vermijden.
Een ander belangrijk element om hier te wijzen, is waar nieuwe stijlen moeten worden toegevoegd en welke stappen dan ook moeten worden gevolgd. Het bovenstaande voorbeeld laat dit zien, maar gezien de inheritance aard van CSS, kan het de moeite waard zijn om het in detail te vermelden.
In projecten waar we Bootstrap als een onderliggend raamwerk hebben gebruikt, hebben we bijvoorbeeld drie plaatsen waar nieuwe regels moeten komen, afhankelijk van wat de ontwikkelaar probeert te bereiken. Daarom hebben we een handleiding toegevoegd aan de documentatie met drie scenario's:
Als u een stijl die door Bootstrap is gedefinieerd wilt overschrijven, dan:
Als u een nieuwe stijldefinitie wilt toevoegen die Bootstrap niet overschrijft en die overal in de applicatie beschikbaar moet zijn, dan:
Als u een nieuwe stijldefinitie voor een component wilt toevoegen (dit betekent dat deze alleen beschikbaar is voor die component, ongeacht de component die in de toepassing wordt gebruikt), dan:
Deze gids:
Uw coderingsstandaarden of CSS-stijlgids verwijst naar de manier waarop uw team is overeengekomen om CSS te schrijven. Dit omvat de beste werkwijzen voor het schrijven van code, zoals opmaak, naamgeving en syntaxisconventies. Veel bedrijven hebben hun manier van doen gedeeld (dit artikel van CSS-Tricks heeft een geweldige compilatie: CSS Style Guides). Hier zijn een paar manieren waarop ik het handig vind om dit soort informatie te delen:
Gebruik dit formaat om te wijzen op de dingen die u wilt vermijden, terwijl u een haalbaar alternatief biedt. Dit verwijdert ambiguïteit en moedigt mensen aan om iets specifieks te doen. Bijvoorbeeld:
| don'ts | do's |
|---|---|
| Gebruik geen tabbladen voor inspringen. | Gebruik vier (4) spaties voor inspringen. |
| Gebruik geen under_scores of "camelCase" om klassen of ID's te benoemen. | Gebruik streepjes om woorden te scheiden. |
Gebruik Klasse- en ID-namen niet om de onderliggende markupstructuur weer te geven. .container overspanningen en .small-header-div zijn slechte namen. | Denk aan CSS in termen van objecten en gebruik eenvoudige zelfstandige naamwoorden als namen. |
| Gebruik geen ID's en overdreven specifieke selectors om in te stijlen. Gebruik deze alleen wanneer dit absoluut noodzakelijk is (bijvoorbeeld formulierelementen of paginaankers). | Gebruik klassen om hergebruik te vergemakkelijken en CSS-selectiespecifieke conflicten te verminderen. |
Vat uw richtlijnen samen in 'best practices' en neem voorbeelden op. Hierdoor wordt iedereen gemakkelijker te lezen en te begrijpen. Bijvoorbeeld:
| Beste praktijken | Voorbeeld |
|---|---|
| Schrijf meerdere selectors op afzonderlijke regels. | .BTN, .btn-link |
| Neem een spatie op tussen de selector en de openingsbrace. | .selector |
| Gebruik steno voor hex-waarden indien mogelijk. | #fff vs #ffffff |
| Schrijf hexadecimale waarden in kleine letters. | # 3d3d3d vs # 3D3D3D |
| Enclose URL's in enkele aanhalingstekens. Over het algemeen hebben enkele aanhalingstekens de voorkeur boven dubbele aanhalingstekens, omdat ze eenvoudiger te typen zijn. | url ('/image.png') vs url ( "/Image.png") |
| Gebruik eenheden niet voor nul (0) waarden, behalve voor hoeken (graden) en tijd (s of ms). | marge-rechts: 0; vs margin-right: 0px; |
De manier waarop een ontwikkelaar code schrijft, kan sterk van de andere afwijken. Dit is waarom het belangrijk is voor uw team om coderingsnormen in te stellen. Dit zorgt ervoor dat de code consistent is in een project, waardoor het gemakkelijker is om te lezen, schrijven en beoordelen. Maar zorg ervoor dat alles wat u in uw coderingsnormen opneemt een praktijk is die uw team heeft afgesproken.
Ik werkte aan een project waarbij we dit in onze gids voor woonstijlen hebben opgenomen. Als onderdeel van de code hebben we deze best practices vastgelegd en naar de repo doorgestuurd. Om er zeker van te zijn dat iedereen aan boord was, moest iedereen in het team het pull-verzoek goedkeuren voordat we het konden samenvoegen. Dit garandeerde dat iedereen tijd moest vrijmaken om het te bespreken en te bespreken.
Wanneer u uw stijlen in kleinere en meer gefocuste stylesheets breekt, is het gemakkelijker om ze te documenteren. U kunt ook tijd besparen door niet te hoeven documenteren wat vanzelfsprekend wordt.
In plaats van een 800-lijnstijlblad met alle variabelen die u in een thema kunt gebruiken, kunt u bijvoorbeeld een bestand voor elk van de variabeletypen hebben. Dit zal tijd besparen door niet op en neer in het bestand te hoeven scrollen om iets te vinden! Denk ook aan de tijd die u kunt besparen door de index niet elke keer bij te werken als u een nieuwe sectie toevoegt of hernoemt.
/ * ------------------------------------------- * \ variables.less Index - Kleurenpalet - Typografie - Knoppen - Formulieren - Lay-out - Berichten & status - Algemeen - Navigatie - Carrousel - Jumbotron \ * ------------------------ ------------------- * /
Een ander voorbeeld om te overwegen bij het werken in grote applicaties is de modlet-workflow. Het verklaart waarom het werken met kleinere bestanden, georganiseerd door componenten, het testen en assembleren ervan in uw app gemakkelijker maakt.
Een groot deel van het goed documenteren van CSS heeft te maken met het schrijven van goede CSS en omgekeerd. Dit betekent dat zelfs wanneer de status van uw CSS-codebasis misschien niet de beste is, het afdwingen van documentatieregels u naar een beter systeem kan brengen.
Dit is waar het documenteren van CSS met een stijlgids in gedachten op zijn plaats komt. Het idee erachter is dat een stijlgids u kan helpen bij het bepalen van een goede structuur voor uw CSS. Om er een te maken, moet u een onderscheid maken tussen:
Het grootste deel van uw CSS moet bestaan uit de basislijnstijlen, omdat deze overal in de toepassing beschikbaar zijn en van invloed zijn op alle elementen in hun standaardstatus. Aangepaste stijlen moeten plaatsvinden als u componenten toevoegt met een specifiek uiterlijk en gedrag, of in de gevallen waarin de lay-out van een element of component op een pagina dit vereist.
Een goede manier om vast te leggen hoe deze specifieke instelling in uw toepassing kan werken, is door een sitemap met stijlgids te maken. Als u eenmaal weet hoe een stijlgids eruit ziet in uw toepassing, kunt u elementen met dat in gedachten documenteren. Als u bijvoorbeeld in uw stijlgids hebt gedefinieerd hoe knoppen en navigaties eruit zien, wordt duidelijk aangegeven waar u nieuwe stijlen en documentatie voor hen zou moeten toevoegen (in "buttons.css" en "navs.css"). Maar hoe zit het met een navigatie die is gemaakt van knoppen?
Het hebben van een stijlgids kan u helpen deze beslissing te nemen, omdat u kunt vergelijken hoe knoppen en navigaties eruitzien, vanuit een weergave en een markup-perspectief. Laten we naar dit voorbeeld kijken:
In dit geval zijn er twee mogelijke locaties voor de CSS die de navigatie van de knoppen definiëren:
Accentsconagua
Nadat u uw stylesheets in meer beheersbare bestanden hebt opgedeeld, kunt u doorgaan met deze oefening door elke stijl in afzonderlijke secties op te splitsen.
Om te beginnen moet elk stylesheet minstens een titel bevatten en (indien nuttig) een korte beschrijving. De titel kan zo simpel zijn als de naam van het bestand, met een hoofdletter die er meer uitziet als een titel (bijvoorbeeld: "Knoppen" voor de stylesheet "buttons.css"), of het kan hetzelfde zijn als de naam van het bestand, zoals deze:
/ ** * icons.css * / .icon font-family: 'bitovi'; spreek: geen; lettertype: normaal; font-gewicht: normaal; lettertype-variant: normaal; text-transform: none; regelhoogte: 1;
Ik vind het gebruik van de bestandsnaam bijzonder handig bij het debuggen van de code in de browser, en meestal als het bestand is gecompileerd met andere bestanden, omdat ik een verwijzing kan krijgen naar het bestand waarin de stijl leeft.
Merk ook op dat de commentaarstijl die ik heb gebruikt opent met / **vs gewoon / *. Dit is een conventie die in JSDoc wordt gebruikt om opmerkingen te analyseren die moeten worden opgenomen in de automatisch gegenereerde documentatie. Ik raad aan deze stijl te gebruiken, aangezien veel generieke stijlgeleiders het JSDoc-formaat gebruiken, dus als u klaar bent om een generator te gebruiken, heeft uw code heel weinig extra werk nodig.
In elk geval kunt u andere stijlen gebruiken om een sectie aan te geven zoals:
/ * -------------------------------------------- * \ icons.css \*-------------------------------------------*/ .icoon font-family: 'bitovi'; spreek: geen; lettertype: normaal; font-gewicht: normaal; lettertype-variant: normaal; text-transform: none; regelhoogte: 1;
Tot op zekere hoogte is dit afhankelijk van wat uw team het erover eens is dat de beste manier is om een onderdeel op te laten vallen. De enige vereiste is om te gebruiken / * aan het begin en * / aan het einde. Wat er echt toe doet, is dat welke benadering je ook gebruikt, je je eraan houdt en het op een consistente manier gebruikt in je CSS-code.
Als u denkt dat een beschrijving nuttig kan zijn in een bepaalde stylesheet, voegt u deze toe als onderdeel van deze eerste opmerking. Bijvoorbeeld:
/ ** * icons.css * * Pictogrammen moeten op een eenvoudige en betekenisvolle manier het concept van de functie * weergeven die zij vertegenwoordigen. Let er bij het ontwerpen van nieuwe pictogrammen op dat u alle complexiteiten * verwijdert en dat u de lineaire en lichte weergave van de iconenset volgt. * / .icon font-family: 'bitovi'; spreek: geen; lettertype: normaal; font-gewicht: normaal; lettertype-variant: normaal; text-transform: none; regelhoogte: 1;
Door dit te doen, wordt het idee versterkt dat het een sectie is. Probeer ook de beschrijving in meerdere regels op te splitsen (Harry Roberts beveelt tot 80 tekens aan), zodat het gemakkelijker leesbaar is terwijl meerdere bestanden geopend zijn of terwijl u het op Github leest..
Nadat u een titel en een beschrijving hebt toegevoegd, kunt u een stap verder gaan door de stijlen in de stylesheet op te splitsen in secties. Denk erover na hoe logisch de inhoud van een stylesheet kan worden uitgelegd. Het stylesheet "buttons.css" heeft bijvoorbeeld meestal een sectie waarin de standaardstijl van een knop wordt gedefinieerd door alleen de klasse toe te passen .BTN. Dan zullen er extra stijlen zijn die verschillende kleuren, grootten en configuraties definiëren die samen kunnen worden toegepast om het uiterlijk en gedrag ervan verder aan te passen. Door secties voor elk van die stijlen te maken, wordt het gemakkelijker om te begrijpen en te vinden waar nieuwe klassen of overschrijvingen moeten verschijnen. Het is ook minder intimiderend om naar een bestand te kijken wanneer de code in fragmenten wordt weergegeven versus een lang bestand, waarbij het moeilijk te zeggen is waar stijlen beginnen en eindigen.
Laten we naar dit vergelijkende voorbeeld kijken. Eerst een LESS-codeblok zonder secties:
.label-gecondenseerde variant (@color) &: voor achtergrondkleur: @color; .label border-radius: 0; font-family: @ font-family-bold; lettergrootte: 85%; positie: relatief; & .label - gecondenseerd font-size: @ font-size-xsmall; kleur: @gray; achtergrond: transparant; padding-right: @ padding-small; & .label - primaire .label-gecondenseerde variant (@ label-primary-bg); & .label - succes .label-condenseerde-variant (@ label-success-bg); & .label - info .label-condenseerde variant (@ label-info-bg); & .label-warning .label - gecondenseerde variant (@ label-warning-bg); & .label - gevaar .label-gecondenseerde variant (@ label-danger-bg); & .label - simple font-family: @ font-family-base; font-size: @ font-size-xsmall - 1; kleur: @gray; rand: 1px vast @ grijs-licht; opvulling: 2px; grensradius: @ border-radius-small; text-transform: hoofdletters;
En hetzelfde codeblok met secties:
/ ** * bootstrap-custom / _labels.less Labels * * Overschrijft de standaardstijlen gedefinieerd door het bootstrap-framework. * * / .label grensradius: 0; font-family: @ font-family-bold; lettergrootte: 85%; positie: relatief; / ** * Gecondenseerde labels * * Hiermee wijzigt u labels om een kleinere en smallere versie met een gekleurde cirkel te maken voor gebieden met weinig ruimte (bijvoorbeeld in lijstweergaven). * / .label & .label - gecondenseerd font-size: @ font-size-xsmall; kleur: @gray; achtergrond: transparant; padding-right: @ padding-small; / ** * Gecondenseerde labels - Kleuren * / .label-condenseerde-variant (@color) // Variantmixing om de cirkelkleur in te stellen &: vóór achtergrondkleur: @color; .label & .label - gecondenseerde & .label - primaire .label-gecondenseerde variant (@ label-primary-bg); & .label - succes .label-condenseerde-variant (@ label-success-bg); & .label - info .label-condenseerde variant (@ label-info-bg); & .label - waarschuwing .label-condenseerde-variant (@ label-warning-bg); & .label - gevaar .label-gecondenseerde variant (@ label-danger-bg); / ** * Eenvoudige labels * * Hiermee worden labels gewijzigd om een eenvoudige lineaire versie te bieden waarin kleuren niet worden gebruikt. * / .label & .label - simple font-family: @ font-family-base; font-size: @ font-size-xsmall - 1; kleur: @gray; rand: 1px vast @ grijs-licht; opvulling: @ opvulling-klein; grensradius: @ border-radius-small; text-transform: hoofdletters;
Dit is een geweldige manier om een momentopname te maken van wat er in het stylesheet staat en een must in die projecten waar, om welke reden dan ook, lange stylesheets aanwezig zijn om te blijven (geen fan van die projecten, maar ze gebeuren wel!).
Een stylesheet-index ziet er normaal gesproken als volgt uit:
/ ** * icons.css * * Pictogrammen moeten op een eenvoudige en betekenisvolle manier het concept van de functie * weergeven die zij vertegenwoordigen. Let er bij het ontwerpen van nieuwe pictogrammen op dat u alle complexiteiten * verwijdert en dat u de lineaire en lichte weergave van de iconenset volgt. * * Index * - Pictogramlettertype * - Pictogramvarianten * - Pictogramanimaties * * /
En hoewel ik hou van hoe netjes en nuttig ze kunnen zijn, moet ik toegeven dat ze gemakkelijk vergeten kunnen worden en daarom verouderd zijn. Ze zijn ook lastig te updaten als ze lang zijn en je cijfers gebruikt (dus vermijd die!)
Een alternatieve manier om indexen te gebruiken, is door een stijlguidegenerator het werk voor u te laten doen door naar uw stylesheets te kijken, de secties te vinden die u hebt gedefinieerd en een index voor u te genereren. Ik zal aan het einde van dit artikel meer over dit onderwerp uitdiepen.
Hier is waar het geheim van het documenteren van leugens. Het is gemakkelijk om je te laten meeslepen en eens in een documentatie-razernij te gaan, om het vervolgens te vergeten en te eindigen met slechts een deel van je codebasis overgedocumenteerd en de rest ongedocumenteerd. Zoals bij alles in het leven, is het geheim het vinden van de balans. Documenteer die gebieden waar aandacht nodig is, want die zijn er onvoorziene afhankelijkheden, extra middelen, of belangrijke aantekeningen in gedachten houden. Dat wil zeggen dat niet elk stukje code moet worden gedocumenteerd, maar het is zeker nuttig om het in brokken op te splitsen en uit te leggen wat die stukjes zijn wanneer dat nodig is. Op deze manier wordt documentatie een handig hulpmiddel dat deel uitmaakt van uw workflow en niet een bijzaak is die u niet hoeft te doen. Maar hoe doe je dat precies? Hier is een voorbeeld:
Laten we zeggen dat u de opmaak en CSS voor het volgende kaartonderdeel gaat implementeren:
Als u naar de ontwerpen kijkt, kunt u de volgende stijlpatronen identificeren:
U kunt dan de CSS-implementatie afbreken met die patronen in gedachten en de documentatie gebruiken om u te begeleiden. Om te beginnen kan uw "cards.css" stylesheet als volgt een eenvoudige intro bevatten:
/ ** * cards.css * * Dit zijn de stijlen voor het kaartonderdeel. * * Index * - Kaartbasis * - Kaartraster * - Kaartlijst * - Kaart Donker * /
U kunt in de inleiding meer nuttige informatie opnemen, maar aangezien u net begint, kan iets eenvoudigs het documentatiekader helpen te leggen.
Laten we vervolgens de secties toevoegen waarin u uw stijlen wilt bewerken:
/ ** * cards.css * * Dit zijn de stijlen voor het kaartonderdeel. * * Index * - Kaartbasis * - Kaartraster * - Kaartlijst * - Kaart Donker * / / ** * Kaartbasis * / / ** * Kaartraster * / / ** * Kaartlijst * / / ** * Kaart Dark * /
Met deze secties in gedachten kunt u visualiseren hoe de code moet worden gestructureerd. U weet dat u de basisdefinities van de kaart flexibel en onafhankelijk genoeg moet maken zodat u de kaart eenvoudig in een raster, lijst of donkere versie kunt laten werken.
Vervolgens kunt u tijdens het schrijven van de code specifieker worden met uw opmerkingen:
/ ** * Kaartbasis * * Bepaalt het uiterlijk en de werking van de standaardkaart met de belangrijkste onderdelen: * - Kaartafbeelding * - Kaartinhoud * - Kaartvoetregel * / .kaart ... .card__image ... .card__logo ... .card__content ... .card__footer ...
Ik beschouw dit als het basisniveau van documentatie dat u moet opnemen, omdat het dient als een leidraad voor het indelen van de code en snel informeert hoe de zaken zijn georganiseerd voor de volgende persoon die eraan werkt.
Het volgende niveau is het toevoegen van opmerkingen die specifiek zijn voor een regel, en die kan worden gebruikt om uit te leggen wat deze regel doet, omdat het niet in één oogopslag duidelijk is. Bijvoorbeeld:
/ ** * Kaartbasis * * Bepaalt het uiterlijk en het gedrag van de standaardkaart met de verschillende onderdelen: * - Kaartafbeelding * - Kaartlogo * - Kaartinhoud * - Kaartvoet * / .card @media (max. Breedte: screen-xs) border: none; / * omdat de kaart 100% van het scherm op mobiel in beslag neemt * / .card__image ... .card__logo ... .card__content flex: 1 1 auto; / * "auto" moet expliciet zijn om te voorkomen dat de div samenvouwt in IE. * /
Het mooie van deze aanpak is dat de documentatie er is om de implementatie te ondersteunen en te informeren terwijl je gaat, in tegenstelling tot iets dat op een later tijdstip wordt toegevoegd.
Hier zijn een paar voorbeelden van het Bootstrap-raamwerk die laten zien wanneer opmerkingen handig zijn en wanneer het de moeite waard is om meer in detail te gaan.
// Need .dropdown-toggle since: last-child is niet van toepassing, // aangezien er direct een .dropdown-menu wordt gebruikt. Btn-group> .btn: last-child: not (: first-child) , .btn-group> .dropdown-toggle: not (: first-child) .border-left-radius (0);
Deze opmerking verduidelijkt waarom deze stijlen bestaan en wat ze doen. Het is ook kort en bondig en communiceert het idee in een ongedwongen taal.
// Checkbox- en radio-opties // // Om de formuliervalidatie-feedback van de browser te ondersteunen, ondersteund door het // 'required' attribuut, moeten we de inputs 'verbergen' via 'clip'. We kunnen // 'display: none; niet gebruiken' of 'zichtbaarheid: verborgen;' zoals dat ook de popover verbergt. // Als u de ingangen alleen via 'dekking' visueel verbergt, blijven ze // in bepaalde gevallen klikbaar, wat wordt voorkomen door 'clip' en 'pointer-events' te gebruiken. // Op deze manier zorgen we ervoor dat een DOM-element zichtbaar is om de popover te positioneren. // // Zie https://github.com/twbs/bootstrap/pull/12794 en // https://github.com/twbs/bootstrap/pull/14559 voor meer informatie. [data-toggle = "buttons"] > .btn,> .btn-group> .btn input [type = "radio"], input [type = "checkbox"] position: absolute; clip: rect (0,0,0,0); pointer-events: geen;
Dit is een geweldig voorbeeld van documentatie die dieper gaat, de logica achter een implementatiebeslissing uitlegt en links naar aanvullende informatie biedt.
Met deze praktische tips in het achterhoofd, is de volgende stap om een leefstijlgids als onderdeel van uw documentatie. Een gids voor levende stijlen is een levend document dat de opmerkingen toont die u in uw code hebt gestructureerd zoals een website, zodat u de documentatie afzonderlijk van de broncode kunt gebruiken.
Wat levende stijlgidsen krachtig maakt, is dat de feitelijke documentatie bij de code hoort en eenvoudig kan worden bijgewerkt terwijl uw code verandert, zodat deze synchroon en relevant blijft. Het bijkomende voordeel is dat u deze documentatie beschikbaar kunt maken voor andere mensen in uw team die mogelijk niet direct met de code communiceren (zoals ontwerpers, productmanagers of QA-engineers). Deze teamleden zouden het ook nuttig vinden om te weten hoe de gebruikersinterface aan het vormgeven is.
In een gids met woonstijlen kunt u interactieve demonstraties van uw code opnemen en kunt u uw documentatie verder organiseren, onafhankelijk van de codestructuur.
Het documenteren van CSS begint met duidelijke regels en een goed gestructureerde codebasis. Wanneer het wordt uitgevoerd als onderdeel van uw werkstroom, kan het ook dienen als een leidraad voor het structureren van uw code en deze georganiseerd te houden terwijl deze groeit. Dit heeft als bijkomend voordeel dat het duidelijk maakt waar dingen zijn en waar nieuwe code moet worden toegevoegd, waardoor het aan boord gaan van nieuwe leden wordt versneld terwijl de ontwikkeling van fast-tracking wordt verbeterd.
