Hallo iedereen!
Mijn naam is Masha, ik werk als kwaliteitsborgingsingenieur in de Tinkoff-bedrijvengroep. QA-werk omvat veel communicatie met verschillende mensen uit verschillende teams, en ik was ook manager en docent van educatieve programma's, dus mijn communicatiekaart was zo breed mogelijk. En op een gegeven moment explodeerde ik: ik besefte dat ik niet meer, ik kan, ik kan helse tonnen onleesbare tabellen en documenten niet meer invullen.
Ieder van jullie heeft zich nu zeker voorgesteld waar ik het over heb, en brak het koude zweet uit: lijsten met achternamen zonder alfabetische volgorde, tabellen met honderden kolommen met een slordige lay-out, tabellen met duizenden regels waarin je je vinger moet wissen op het muiswiel om de koers te bekijken, tonnen pagina's met ongenummerde instructies, honderden brieven die naar elkaar zijn verzonden met gegevens die moeten worden geanalyseerd en gesystematiseerd en in dezelfde onleesbare tabellen moeten worden gestopt.
En dus, toen ik een beetje was afgekoeld, besloot ik dit artikel te schrijven. Ik zal het hebben over hoe u normaal gesproken (soms zelfs handig) een verscheidenheid aan niet-productdocumentatie kunt onderhouden. Ik hoop dat het artikel zich over het netwerk zal verspreiden en dat het niveau van de hel in de afdelingen naast de ontwikkeling in ieder geval een beetje zal dalen, en dat mensen (inclusief ikzelf) een beetje gelukkiger zullen worden.
Gereedschap
Productdocumentatie wordt vaak naast code bewaard, wat een goede zaak is. En niet-productdocumentatie wordt meestal overal opgeslagen. Vaak proberen mensen informatie van verschillende plaatsen in Confluence te brengen, en wij zijn daarop geen uitzondering. Dus de rest van het verhaal gaat over hem.
Over het algemeen is Confluence een geavanceerde wiki-engine. Hiermee kunt u werken met gegevens in verschillende soorten weergave: tekst met opmaak, tabellen, verschillende grafieken. Dit is een zeer interessante en krachtige tool, maar als je niet weet hoe je het moet koken, krijg je weer een hoop onleesbare documenten. Ik zal je leren koken!
macros
Bijna alle magie van Confluence is opgebouwd rond macro's. Er zijn veel macro's en ze kunnen met elkaar worden gecombineerd. Ze zijn betaald en gratis, verder zullen er verschillende voorbeelden van macro's zijn met koppelingen naar documentatie ervoor.
De interface voor het werken met macro's is zo eenvoudig mogelijk. Om een macro toe te voegen, moet u op de plus klikken en het gewenste element uit de lijst selecteren.
Als de macro zelfvoorzienend is, dat wil zeggen, er hoeft niets anders in zichzelf te worden ingevoegd, het ziet eruit als een blok.
Als een macro iets nodig heeft om te werken, ziet het eruit als een doos.
Tegelijkertijd kun je zoveel anderen als je wilt in één frame plaatsen, zolang er maar logica in je piramide zit.
Elke macro heeft een preview: je ziet meteen of je de macro goed hebt ingevuld en geconfigureerd.
templates
Naast macro's is er een handige tool voor het vooraf invullen van inhoud - dit is een sjabloon.
Sjablonen kunnen worden gebruikt bij het maken van elke pagina: klik gewoon op de drie puntjes naast de knop "Create" en selecteer het gewenste sjabloon.
Vervolgens wordt alle inhoud in de sjabloon toegevoegd aan de gemaakte pagina.
Iedereen kan pagina's maken van sjablonen, maar alleen degenen die de rechten hebben om zelf sjablonen te maken of te bewerken, kunnen pagina's maken. U kunt aanvullende instructies aan de sjabloon toevoegen over hoe de pagina moet worden onderhouden.
Tafel Magie
Eigenlijk ben ik als techneut dol op tabellen en kan ik er bijna alle informatie in verwerken (hoewel dit niet altijd effectief is). De tabellen zelf zijn duidelijk, gestructureerd, schaalbaar, magisch!
Maar zelfs zo'n prachtig geheel als een tafel kan bedorven worden. En het kan met succes worden gebruikt en zelfs verbeterd. Hieronder meer daarover.
Filteren (betaalde plug-in)
Elke grote onleesbare tabel kan iets minder groot en iets leesbaarder worden gemaakt met behulp van filtering. Hiervoor kunt u een betaalde macro gebruiken .
Binnen deze macro moet je een tafel schuiven (zelfs de lelijkste is mogelijk, het belangrijkste is om hem helemaal te schuiven). In de macro kunt u kolommen selecteren voor vervolgkeuzefilter, tekstfilter, numeriek filter en datumfilter.
Stelt u zich eens voor dat alle informatie over kandidaten voor alle vacatures wordt vastgelegd in een lijst in tabelvorm. Uiteraard ongesorteerd - mensen komen niet in alfabetische volgorde naar interviews. En u moet begrijpen of u eerder een specifieke sollicitant hebt geïnterviewd. U hoeft alleen maar deze hel in een filtermacro te plaatsen, een tekstfilter op achternaam toe te voegen - en voila, de informatie staat op uw scherm.
Het is vermeldenswaard dat het filteren van enorme tabellen de systeemprestaties en laadtijd van pagina's kan beïnvloeden, dus het plaatsen van een enorme tabel in het filter is een tijdelijke steunpilaar. Het is beter om een proces te bouwen waarin mensen geen enorme onleesbare tabellen hoeven te maken (een voorbeeld van het proces staat aan het einde van het artikel).
Sorteren (betaalde plug-in)
Met magische macro u kunt ook de standaardsortering instellen op elke kolom en de rijen nummeren. Of klik op een willekeurige kolom van de tabel die in de filtermacro is geplaatst en sorteer op deze kolom.
U hebt bijvoorbeeld dezelfde tafel met sollicitanten en u moet uitzoeken hoeveel interviews er in een bepaalde maand zijn gehouden - sorteer op datum en verheug u.
Draaitabellen (betaalde plug-in)
Laten we nu verder gaan met een interessanter geval. Stel je voor dat je tafel enorm is en dat je er iets op moet berekenen. Je kunt het natuurlijk kopiëren naar Excel, berekenen wat je nodig hebt en de gegevens weer uploaden naar Confluence. Kun je een macro een keer toepassen? en krijg hetzelfde resultaat, alleen bijgewerkt.
Bijvoorbeeld: je hebt een tabel met de gegevens van alle werknemers - waar ze geografisch gelokaliseerd zijn en welke functies ze bekleden. Om te berekenen hoeveel mensen er in elke stad zijn, moet u in de macro "Draaitabel" de rij selecteren waarmee de gegevens worden samengevoegd (locatie) en het type bewerking (optellen).
U kunt natuurlijk op meerdere criteria tegelijk groeperen, u ziet alle mogelijkheden .
Grafieken (betaalde plug-in)
Zoals ik al zei, niet iedereen houdt zoveel van tafels als ik. Helaas houden de meeste managers er helemaal niet van. Maar iedereen houdt van felle kleurenkaarten.
De makers van Confluence wisten hier zeker van (ze hebben zeker ook bazen die dol zijn op rapporten en grafieken, waar zouden ze zijn zonder). Daarom kunt u de magische macro gebruiken . In deze macro moet je de draaitabel uit de vorige alinea plaatsen, en voila - je saaie grijze gegevens worden prachtig gevisualiseerd.
Uiteraard heeft deze macro ook instellingen. Een link naar de documentatie voor elke macro is te vinden in de bewerkingsmodus van die macro.
Gemak van aggregatie
De informatie uit de vorige paragrafen was waarschijnlijk geen openbaring voor u. Maar nu weet je zeker hoe je macro's moet gebruiken, en ik kan verder gaan met het interessantere deel van het artikel.
Tags
Het is erg als mensen informatie opslaan in één ongestructureerd artikel of een enorme tabel. Erger nog is wanneer delen van deze informatie niet alleen onleesbaar zijn, maar ook verspreid over de uitgestrektheid van Confluence. Gelukkig is het mogelijk om verspreide informatie op één plek te verzamelen. Hiervoor moet je gebruiken (tags die bij iedereen op sociale netwerken bekend zijn).
Elk aantal tags kan aan elke pagina worden toegevoegd. Als u op een tag klikt, wordt u naar een aggregatiepagina gebracht met links naar alle materialen met deze tag, evenals een reeks gerelateerde tags. Gerelateerde tags zijn tags die vaak op dezelfde pagina verschijnen.
Pagina eigenschappen
U kunt nog een interessante macro aan de pagina toevoegen voor het structureren van informatie - . Daarin moet u een tabel met twee kolommen indienen, de eerste is de sleutel en de tweede is de waarde van het onroerend goed. Bovendien kan de macro van de pagina worden verborgen zodat deze het lezen van de inhoud niet belemmert, maar de pagina wordt nog steeds gemarkeerd met de benodigde toetsen.
Let op de ID - het is handig om deze in te stellen om verschillende groepen eigenschappen op verschillende pagina's te hangen (of zelfs verschillende groepen eigenschappen op één pagina).
rapporten
Door middel van tags kunt u rapporten verzamelen. Bijvoorbeeld macro verzamelt alle pagina's met een bepaalde set tags.
Maar een interessanter rapport is een macro . Het verzamelt ook alle pagina's met een bepaalde set tags, maar geeft ze niet alleen weer, maar stelt een tabel samen (snap je het verband met het begin van het artikel?), waarin de kolommen de sleutels zijn van de pagina-eigenschappen.
Het blijkt een samenvattende tabel met informatie uit verschillende bronnen. Het is leuk dat het handige functies heeft: adaptieve lay-out, sorteren op elke kolom. Ook kan zo'n rapportagetabel binnen de macro worden geconfigureerd.
Bij het configureren kunt u enkele kolommen uit het rapport verwijderen, de standaardstatus of het aantal weergegeven records instellen. U kunt ook de ID van de pagina-eigenschap instellen om alleen de informatie te zien die u nodig hebt.
U hebt bijvoorbeeld veel werknemerspagina's, deze pagina's hebben een reeks eigenschappen over een persoon: op welk niveau hij is, waar hij is, wanneer hij bij het team kwam, enzovoort. Deze eigenschappen zijn gemarkeerd id = werknemer_inf. En er is een tweede reeks eigenschappen op dezelfde pagina, die informatie bevat over een persoon als onderdeel van een team: welke rol de persoon vervult, in welk team hij zit, enzovoort. Deze eigenschappen zijn gemarkeerd ID = team_inf. Vervolgens kunt u bij het samenstellen van een rapport slechts informatie voor één of twee ID's tegelijk weergeven - afhankelijk van wat het handigst is.
Het mooie van deze aanpak is dat iedereen de informatietabel kan verzamelen die ze nodig hebben, die niets dupliceert en wordt bijgewerkt wanneer de hoofdpagina wordt bijgewerkt. Bijvoorbeeld: een teamleider maakt het niet uit wanneer zijn ontwikkelaars een baan krijgen, maar het is belangrijk welke rol elk van hen in het team speelt. De teamleider verzamelt een rapport over het team. En het maakt de accountant niet uit wie welke rol vervult, maar de functies zijn belangrijk - hij zal een rapport over de functies verzamelen. In dit geval wordt de informatiebron niet gedupliceerd of overgedragen.
Laatste proces
Instructie
We kunnen dus informatie prachtig structureren en effectief samenvoegen in Confluence met behulp van macro's als voorbeeld. Maar idealiter moet u ervoor zorgen dat nieuwe informatie onmiddellijk wordt gestructureerd en terechtkomt in alle aggregatiemechanismen die al in gebruik zijn.
Hier komen een aantal macro's en sjablonen te hulp. Om mensen nieuwe pagina's in het juiste formaat te laten maken, kunt u de macro Maken van sjabloon gebruiken. Het voegt een knop toe aan de pagina, door erop te klikken wordt een nieuwe pagina gemaakt op basis van de sjabloon die u nodig hebt. Zo laat je mensen direct werken in het formaat dat jij nodig hebt.
In de sjabloon van waaruit u een pagina kunt maken, moet u vooraf labels, de macro "Pagina-eigenschappen" en een tabel met de eigenschappen toevoegen die u nodig hebt. Ik raad ook aan om instructies toe te voegen over met welke waarden de pagina moet worden gevuld en over eigenschapswaarden.
Dan ziet het uiteindelijke proces er als volgt uit:
- U maakt een sjabloon voor een specifiek type informatie.
- Voeg in deze sjabloon labels en pagina-eigenschappen toe aan een macro.
- Maak op elke geschikte plaats een hoofdpagina met een knop, door te klikken waarop een onderliggende pagina wordt gemaakt op basis van de sjabloon.
- Start op de hoofdpagina van gebruikers die mogelijk de nodige informatie zullen genereren (volgens het gewenste sjabloon, door op de knop te klikken).
- Verzamel zelf een rapport over de eigenschappen van de pagina via de tags die u in de sjabloon hebt opgegeven.
- Verheug je: je hebt alle informatie die je nodig hebt in een handig formaat.
Valkuilen
Als kwaliteitsingenieur kan ik gerust zeggen dat niets perfect is in de wereld. Zelfs goddelijke tafels zijn onvolmaakt. En er zijn valkuilen in het bovenstaande proces.
- Als u besluit de namen of samenstelling van de pagina-eigenschappen te wijzigen, moet u alle reeds gemaakte objecten bijwerken, zodat hun gegevens correct in het samenvattingsrapport worden opgenomen. Dit is triest, maar aan de andere kant dwingt het je om in detail na te denken over de "architectuur" van je informatieset, wat een zeer interessante taak is.
- U zult een behoorlijke hoeveelheid instructies moeten schrijven over het invullen van de informatietabellen en het gebruik van de tags. Maar aan de andere kant kun je dit artikel gewoon naar de juiste mensen gooien.
Een voorbeeld van het opslaan van niet-productdocumentatie
Via het hierboven beschreven proces kunt u de opslag van bijna alle informatie organiseren. Het mooie van de aanpak is dat deze universeel is: als gebruikers er eenmaal aan gewend zijn, maken ze er geen rommel meer van. Ook een groot (maar niet gratis) pluspunt is de mogelijkheid om on-the-fly verschillende statistieken te verzamelen en er prachtige diagrammen op te tekenen.
Ik zal een voorbeeld geven van ons proces om informatie over het team bij te houden.
Voor elke persoon in het team hebben we besloten om een werknemerskaart aan te maken. Daarom hebben we een sjabloon volgens welke elke nieuwe persoon deze kaart voor zichzelf maakt en al zijn persoonlijke gegevens erin bewaart.
Zoals u kunt zien, hebben we een gedetailleerde lijst met eigenschappen en hebben we meteen instructies voor het onderhouden van deze pagina. Sommige tags worden door de medewerkers zelf aangebracht volgens de instructies, in het sjabloon alleen de belangrijkste: de kaarttag medewerker-kaart, richtingslabel regie-betrekking en opdrachtlabel team-qa.
Als gevolg hiervan wordt, nadat iedereen een kaart voor zichzelf heeft gemaakt, een complete tabel met informatie over werknemers verkregen. Deze informatie kan op verschillende punten worden gebruikt. Resourcemanagers kunnen algemene tabellen voor zichzelf verzamelen en teamleiders kunnen opdrachttabellen verzamelen door een teamtag aan de selectie toe te voegen.
Door middel van tags kun je verschillende samenvattingen zien, bijvoorbeeld door qa-upgradeplan alle taken voor QA-ontwikkeling worden weergegeven. Tegelijkertijd bewaart elke persoon in zijn werknemerskaart een belangrijk verhaal en zijn eigen ontwikkelingsplan - hij maakt een geneste pagina van de sjabloon voor ontwikkelingsplannen.
Conclusie
Bewaar alle documentatie op een zodanige manier dat u zich er niet voor schaamt en dat gebruikers niet ondraaglijk gekwetst worden!
Ik hoop echt dat het artikel nuttig zal zijn en dat er orde zal komen in alle documentatie van de wereld.
Bron: www.habr.com