Ontwikkelen van gebruiksaanwijzingen. OOO Technische documentatie

Er zijn veel soorten voorzieningen achtergrond informatie voor de gebruiker - dit is FAQ (veelgestelde vragen, veelgestelde vragen) en online hulp en gebruikershandleiding (gebruikershandleiding) en de populaire tips van vandaag (coachmarks, zie voorbeeld hieronder), trainingsvideo's en andere.

Er zijn verschillende redenen waarom u een systeemhandleiding moet schrijven. Te beginnen met de verzoeken van de klant (in mijn ervaring was er een geval waarin de klant na elke iteratie een gebruikershandleiding moest aanleveren, zodat hij deze kon gebruiken om acceptatietesten uit te voeren van de functionaliteit van de iteratie) en eindigend met de voorwaarden van de contract met betrekking tot de levering van afgewerkte software, als we het hebben over softwareontwikkeling op bestelling. Bij het ontwikkelen van een eigen product is het schrijven van een gebruikershandleiding ook vaak het geval.

Een analist is vaak betrokken bij het maken van een handleiding als het niet mogelijk is om een ​​technisch schrijver toe te vertrouwen. In de overgrote meerderheid van de gevallen is het de analist die de meest volledige kennis van het systeem heeft, hij heeft ook het vermogen om zijn gedachten duidelijk schriftelijk uit te drukken vanwege de specifieke kenmerken van het beroep. Daarom heb ik meer dan eens te maken gehad met het maken van gebruikershandleidingen.

Hier zijn een paar praktijken voor het schrijven van een goede gebruikershandleiding. Sommigen van hen zullen misschien nuttig zijn voor iemand bij het schrijven van specificaties voor vereisten.

1. Normen

Vaak is het nodig om een ​​document te schrijven dat voldoet aan de eisen van de huidige normen. Het kan zijn:

• IEEE Std 1063-2001, "IEEE Standard for Software User Documentation";
• GOST 19:
  • GOST 19.402-78 ESPD. Programma beschrijving;
  • GOST 19.502-78 ESPD. Algemene beschrijving. Eisen aan inhoud en vormgeving;
  • GOST 19.503-79 ESPD. Handleiding voor systeemprogrammeur. Eisen aan inhoud en vormgeving;
  • GOST 19.504-79 ESPD. Handleiding voor programmeurs. Eisen aan inhoud en vormgeving;
  • GOST 19.505-79 ESPD. Handleiding. Eisen aan inhoud en vormgeving.

Als de behoeften van het project u toelaten om geen rigide normen te volgen, kan het bestuderen van deze documenten in elk geval als uitgangspunt dienen voor het schrijven van een kwaliteitsdocument.

Het MetaGuide-boek van Yury Kagarlitsky kan ook nuttig zijn. Een handleiding voor ontwikkelaars van technische documentatie voor software.

2. Structuur

Denk goed na over de structuur van het document: het moet alle functionaliteit van het systeem dekken, volledig en begrijpelijk zijn.

Een goede gebruikershandleiding moet het volgende bevatten:

• annotatie, dat een samenvatting geeft van de inhoud van het document en het doel ervan. Het wordt ook aanbevolen om aan het begin van elk hoofdgedeelte een korte samenvatting te schrijven.
• Invoering met informatie over hoe u deze handleiding het beste kunt gebruiken
• Inhoud
• hoofdstukken beschrijven hoe gebruiken AAN
• Woordenlijst En
• Onderwerpindex

De gebruikershandleiding kan ook het volgende bevatten:

• FAQ en antwoorden op hen
• Links voor meer informatie over het systeem
• Hoofdstuk mogelijk beschrijven Problemen en manieren om ze op te lossen

Alle hoofdstukken en paragrafen, evenals figuren en tabellen, dienen bij voorkeur te worden genummerd, zodat er in dit document of vanuit een ander document naar kan worden verwezen.

3. Gebruikers

Denk aan typische gebruikers van deze software: het is noodzakelijk dat het document hen helpt bij het oplossen van hun directe problemen.

Het kan zelfs zinvol zijn om verschillende partities (of zelfs verschillende documenten) voor verschillende groepen gebruikers, als hun interactie met het systeem radicaal anders zal zijn. Systeembeheerders (verantwoordelijken voor accounts, toegangsrechten, enz.) zullen bijvoorbeeld geïnteresseerd zijn in totaal andere functionaliteit dan gewone gebruikers.

Respecteer de gebruikers van het systeem, schrijf geen instructies in een kleinerende stijl.

4. Kenmerken van presentatie

Onthoud dat de presentatiestijl in mondelinge spraak of in een zakelijke brief verschilt van die in technische documentatie, en in het bijzonder in de gebruikershandleiding.

De leiderschapsstijl moet neutraal-formeel zijn - het gebruik van stilistisch gekleurde woorden leidt de gebruiker af van de essentie.

Om een ​​goed document te schrijven komt kennis van grammatica en een beetje psychologie goed van pas.

4.1 Schrijf beknopt en logisch. Geef geen onnodige details, dupliceer geen informatie. De volgorde van het vermelden van informatie in de gebruikershandleiding moet overeenkomen met de volgorde van gebruikersacties:

Mooi zo: Selecteer in het menu Bestand Opslaanitem.
Slechter:Kies Opslaan item uit het menu Bestand.

4.2 Gebruik de gebiedende wijs, gebruik geen beleefde uitdrukkingen (alstublieft, zou kunnen, enz.) - overmatige beleefdheid zal hier een belemmering zijn.

Mooi zo: Klik uitloggen.

Slechter: Het is nodig om te klikken uitloggen om uit te loggen huidige gebruikers account van het systeem .

Slechter: Als de gebruiker zijn huidige gebruikersaccount wil uitloggen van het systeem (de systemen), moet hij klikken op uitloggen.

4.3 Structuurinformatie. U kunt vaak het advies vinden om lijsten te vermijden, maar informatie die is gestructureerd in stappen wordt altijd beter waargenomen.

Mooi zo:
Naarcreërenprojecteren:

1. Klik op de Creëren knop op de werkbalk.
2. Op de Creëren projecteren overlay vul alle verplichte velden in.
3. Klik op de Opslaanknop om het project op te slaan.

Slechter: Om een ​​project aan te maken, klik op de Creëren knop op de werkbalk, op de Project maken overlay vul alle verplichte velden in, klik op de Opslaan om het project op te slaan.

4.4 Gebruik geen toekomst of verleden tijd. Zo zijn er vaak handleidingen waarin de reactie van het systeem op de actie van de gebruiker wordt overgebracht door zinnen die in de toekomende tijd zijn geformuleerd. Software heeft geen verleden of toekomst: alles gebeurt in het heden als direct gevolg van een specifieke gebruikersactie. Zodra er een gebeurtenis plaatsvindt, reageert de software.

Mooi zo: Wanneer de gebruiker op de klikt Begin knop, het programma begint het proces.

Slechter: Wanneer de gebruiker op de klikt Begin knop, het programma zal beginnen het proces.

4.5 Controleer de betekenis van woorden. Als u een document moet schrijven buitenlandse taal, moeten we fouten in verband met onvoldoende kennis van de taal zoveel mogelijk proberen te vermijden.

Het werkwoord "drukken" betekent bijvoorbeeld het indrukken van een toets op het toetsenbord, en "klikken" betekent klikken op een knop of pictogram in een programmavenster met de muis, en "slaan" is over het algemeen een slangwoord.

Spelfouten zijn uiteraard onaanvaardbaar.

4.6 Gebruik geen synoniemen voor dezelfde term. IT-literatuur in het Engels (of een andere) taal heeft standaard set actiewerkwoorden (klik, dubbelklik, selecteer, typ, druk, enz.) en dezelfde standaardreeks besturingsnamen. Bepaal de terminologie en houd u eraan in het hele document.

Laat de vervolgkeuzelijst bijvoorbeeld niet vervolgkeuzelijst worden genoemd in een deel van het document en exact hetzelfde element met de naam combobox of vervolgkeuzelijst in een ander deel van het document. Dit brengt de gebruiker in verwarring.

4.7 Gebruik afkortingen verstandig en vermijd jargon.

Er wordt aangenomen dat afkortingen niet mogen worden gebruikt, maar als een lange term meerdere keren wordt gebruikt, is het bij de eerste vermelding in de tekst noodzakelijk om de volledige naam te schrijven en ernaast - een afkorting tussen haakjes, en dan alleen de afkortingen kunnen in de tekst worden gebruikt. Als het document een woordenlijst of een verkort gedeelte bevat, moeten ze daar worden getranscribeerd.

Gebruik geen jargon, metaforen of termen die zijn ontleend aan een andere taal dan de taal van de handleiding.

5. Uiterlijk:

5.1 Overweeg documentstijl. Het zou kunnen bedrijfssjabloon of een softwarekleurenschema of een op maat gemaakt ontwerp voor het document.

Voel je vrij om tijdens het schrijven belangrijke dingen te benadrukken met stijlen of kleuren (markeer bijvoorbeeld de namen van knoppen) vetgedrukt). Maar het is belangrijk om te begrijpen dat verkeerd gekozen lettertypen en kleuren het moeilijk kunnen maken om de inhoud van het document te lezen.

5.2 Bespaar ruimte- breek de tekst op in korte alinea's, gebruik relatief grote koppen, start nieuwe sectie van een nieuwe pagina. Dit zal de perceptie van de door de gebruiker gelezen informatie vergemakkelijken.

5.3 Gebruik pictogrammen en illustraties. Men is van mening dat je je niet moet laten meeslepen door illustraties en ook pictogrammen (iconen) in de tekst in de gebruikershandleiding moet opnemen. Grafische informatie wordt echter altijd beter waargenomen en onthouden, dus schermafbeeldingen en de benodigde pictogrammen moeten in voldoende maar redelijke hoeveelheden in een goede handleiding aanwezig zijn.

6. Ondersteuning:

Verlies niet uit het oog dat software in de loop van de tijd verandert, wat betekent dat uw document ook moet veranderen om up-to-date te blijven.

Conclusie

Houd er rekening mee dat de ergernis van een document van slechte kwaliteit door de gebruiker op de software kan worden geprojecteerd en zo de beslissing om het product te gebruiken kan beïnvloeden.

Onthoud het belangrijkste: het document moet gebruikers helpen.

Artikel voorbereid

Tarasyuk Nadezhda, lid van de sitegemeenschap,

Analist met 6 jaar ervaring in het veld.

Gebruikershandleiding

Gebruikershandleiding(Engels) gebruikershandleiding of handleiding), handmatig, Handleiding Een document dat tot doel heeft mensen te helpen een systeem te gebruiken. Het document maakt deel uit van de technische documentatie voor het systeem en wordt meestal opgesteld door een technisch schrijver.

De meeste gebruikershandleidingen bevatten naast tekstuele beschrijvingen ook afbeeldingen. Bij software worden meestal screenshots in de handleiding opgenomen en bij hardwarebeschrijvingen eenvoudige en begrijpelijke tekeningen of foto's. Er wordt gebruik gemaakt van stijl en taal die toegankelijk zijn voor het beoogde publiek, en het gebruik van jargon wordt tot een minimum beperkt of tot in detail uitgelegd.

Een typische gebruikershandleiding bevat:

• Annotatie die een samenvatting geeft van de inhoud van het document en het doel ervan
• Inleiding met links naar gerelateerde documenten en informatie over hoe u deze handleiding het beste kunt gebruiken
• Inhoudsopgave
• Hoofdstukken die beschrijven hoe te gebruiken tenminste, de belangrijkste functies van het systeem
• Hoofdstuk waarin mogelijke problemen en oplossingen worden beschreven
• Veelgestelde vragen en antwoorden
• Waar anders informatie over het onderwerp te vinden, contactgegevens
• Woordenlijst en, in grote documenten, onderwerpindex

Alle hoofdstukken en paragrafen, evenals figuren en tabellen, zijn meestal genummerd zodat er in het document of vanuit een ander document naar kan worden verwezen. De nummering maakt het ook gemakkelijker om naar delen van de handleiding te linken, bijvoorbeeld wanneer de gebruiker communiceert met het ondersteuningsteam.

normen

Structuur en inhoud van het document Gebruikershandleiding geautomatiseerd systeem worden geregeld door subsectie 3.4 van het document RD 50-34.698-90. Structuur en inhoud van documenten Handleiding, Programmeursgids, Handleiding voor systeemprogrammeur gereguleerd door respectievelijk GOST 19.505-79, GOST 19.504-79 en GOST 19.503-79.

• Een reeks normen en richtlijnen voor geautomatiseerde systemen(GOST 34)
  • RD 50-34.698-90 GEAUTOMATISEERDE SYSTEMEN. VEREISTEN VOOR DE INHOUD VAN DOCUMENTEN
• Het Unified System for Design Documentation (ESKD) definieert het document "Operating Manual" en andere documenten:
  • GOST 2.601-2006 Operationele documenten
  • GOST 2.610-2006 Regels voor de implementatie van operationele documenten
• Het Unified Program Documentation System (ESPD) definieert de documenten "Operator's Guide", "Guide to onderhoud» en hun structuur:
  • GOST 19.101-77 Soorten programma's en programmadocumenten
  • GOST 19.105-78 Algemene vereisten voor programmadocumenten
  • GOST 19.505-79 Gebruikershandleiding. Vereisten voor inhoud en ontwerp
  • GOST 19.508-79 Onderhoudshandleiding. Vereisten voor inhoud en ontwerp

zie ook

Links

• Gebruikershandleiding. Een voorbeeld van registratie volgens KB 50-34.698-90
• Gratis gebruikershandleidingen voor consumentenelektronica
• Site van ontwikkelaars van technische documentatie (technische schrijvers)

• MetaGuide - een gids voor ontwikkelaars van technische documentatie voor software
• Veelvoorkomende fouten in de hulp van softwaregebruikers en hoe u ze kunt vermijden

Wikimedia Stichting. 2010 .

Zie wat de "Gebruikershandleiding" is in andere woordenboeken:

Bijv. aantal synoniemen: 4 instructie (28) handleiding (5) paspoort (17) ... Synoniem woordenboek

gebruikershandleiding- — [E.S. Alekseev, A.A. Myachev. Engels Russisch woordenboek in computersysteemtechniek. Moskou 1993] Onderwerpen informatietechnologie in het algemeen EN gebruikershandleiding handleiding ...

gebruikershandleiding

gebruikershandleiding voor accreditatie en aanvraag voor de Olympische Spelen- [Afdeling taalkundige diensten van het organisatiecomité van Sochi 2014. Verklarende woordenlijst] Sportonderwerpen (Game-services) EN accreditatie en inschrijvingen in de gebruikersgids van de Olympische Spelen … Technisch vertalershandboek

Leiderschap: Leiderschap is de controle over het gedrag van andere mensen (zie Macht). Een handleiding is een set regels om iets te doen of te gebruiken (zie instructies). Zie ook Gebruikershandleiding Organisatiehandleiding Handleiding ... Wikipedia

handleiding- - [A.S. Goldberg. Engels Russisch energiewoordenboek. 2006] Energieonderwerpen in het algemeen EN gebruikersgids … Technisch vertalershandboek

handleiding- vartotojo instrukcija statusas T sritis automatika atitikmenys: engl. gebruikershandleiding; gebruikershandleiding vok. Benutzeranleitung, f; Benutzerhandbuch, n rus. gebruikershandleiding, pr. mededeling van de presentatie, f ... Automatikos terminų žodynas

BUDGETGIDS- BUDGETHANDLEIDING Budgetontwikkeling kan tot op zekere hoogte worden vereenvoudigd als het bedrijf een handleiding voor budgetontwikkeling heeft die de ontwikkelingsprocedure documenteert en de belangrijkste richtingen definieert die moeten worden gevolgd op ... ... Encyclopedia of Banking and Finance

gebruikershandleiding- vartotojo žinynas statusas T sritis automatika atitikmenys: engl. gebruikerslijst; gebruikershandleiding; gebruikershandleiding vok. Bedienungsanleitung, f; Benutzerauskunftsdatei, f; Benutzerhandbuch, n rus. gebruikershandleiding, n; gebruikershandleiding, m… … Automatikos terminų žodynas

R 50.1.041-2002: Informatietechnologieën. Gebruikersorganisatie Open System Environment Profile (OSE) Design Guide- Terminologie R 50.1.041 2002: Informatie Technologie. Ontwerpgids voor omgevingsprofielen open systeem(COS) gebruikersorganisaties: 3.1.1 geaccrediteerde normontwikkelingsorganisatie ... ... Woordenboek-referentieboek met termen van normatieve en technische documentatie

Boeken

• UML-taal. Gebruikershandleiding, Butch Grady. Dit boek wordt geproduceerd in overeenstemming met uw bestelling met behulp van Print-on-Demand-technologie. De Unified Modeling Language (UML) is een grafische taal voor…

Voor veel softwareontwikkelaars is het maken van technische documentatie geen gemakkelijke taak. In de eerste plaats omdat het nauwgezet en saai werk met zich meebrengt dat weken kan duren. Om een ​​applicatie te beschrijven, moet je de functies zorgvuldig doornemen, veel schermafbeeldingen maken en ze in Tekstdocument, voeg beschrijvingen, uitleg, toelichtingen en annotaties toe, werk aan de structuur...

Wat heb je nodig om een ​​helpbestand te maken? De meesten gebruiken hiervoor de PrntScr-knop en een teksteditor. Maar in feite kun je ze allebei weigeren. Er zijn programma's en webservices waarvan veel ontwikkelaars (en zelfs technische schrijvers) gewoon niet weten dat ze bestaan. Gespecialiseerde oplossingen voor het maken van handleidingen, gebruikershandleidingen en andere soortgelijke documenten combineren in de regel een teksteditor met een minimum aan functies, een screenshot-applicatie en hulpmiddelen voor het exporteren naar populaire documentformaten. Bovendien doen sommige van deze programma's het meeste werk voor de gebruiker, door de schermafbeeldingen in de juiste volgorde te plaatsen en zelfs beschrijvingen toe te voegen. Laten we de vijf meest succesvolle analyseren - naar onze mening.

⇡ Clarify 2.0.5 - snelle tutorials zonder extra software

• Ontwikkelaar: Blue Mango leersystemen.
• Besturingssysteem: Windows/Mac.
• Distributie: shareware, $30.
• Russische interface: nee.

In de breedste zin is Clarify een vereenvoudigde teksteditor die tools toevoegt om snel screenshots te maken. Deze eenvoudige zin verbergt echter vele uren tijd die kan worden bespaard door de samenstellers van technische documentatie. Met Clarify hoef je niet constant tussen twee applicaties te schakelen en tijd te verspillen aan het plakken van screenshots - alles staat op één plek.

Het programmavenster is in twee delen verdeeld: aan de linkerkant lopende werkzaamheden met koppen, en aan de rechterkant - met de inhoud van de handleiding. Elke kop wordt hier een "stap" genoemd. Zodra de auteur een nieuwe titel aanmaakt, vraagt ​​het programma je om er een screenshot van te maken en begeleidende tekst toe te voegen. Elke nieuwe kop wordt automatisch genummerd en u kunt eenvoudig subkoppen maken die ook genummerd zijn. Als uw document echter geen sectienummers nodig heeft, kunt u deze functie eenvoudig uitschakelen. Met behulp van sneltoetsen kunnen koppen snel tussen secties worden verplaatst.

Om ergens in de documentatie een screenshot toe te voegen, selecteert u gewoon gewenste titel en klik op de knop voor schermopname. Als er eerder schermafbeeldingen zijn gemaakt, kunt u deze aan het document toevoegen door het pad ernaar op schijf op te geven. Een screenshot kan direct of met een korte vertraging (tot vijf seconden) worden gemaakt, wat handig kan zijn als u een screenshot moet maken van een vervolgkeuzemenu of ander interface-element dat niet constant op het scherm wordt weergegeven. Door op de "Spatie"-toets te drukken, kunt u schakelen tussen het vastleggen van het volledige scherm of het huidige venster. Daarnaast zijn er sneltoetsen beschikbaar om de weergave van de cursor in of uit te schakelen en om een ​​gebied van dezelfde grootte als de vorige schermafbeelding vast te leggen. De laatste functie is erg handig als je tientallen van hetzelfde type screenshots moet maken, omdat dit tijd bespaart bij het selecteren van het gewenste gebied.

Het resulterende screenshot wordt onmiddellijk ingevoegd in het documentatie-item dat is gemarkeerd. Wat interessant is: op de navigatiebalk worden items waarvoor al screenshots zijn toegevoegd visueel gemarkeerd. Hierdoor kun je direct bepalen aan welke onderdelen je moet werken.

Het formaat waarin de schermafbeelding wordt opgeslagen, wordt bepaald in de applicatie-instellingen. Het programma kan automatisch ALT-tags voor afbeeldingen genereren, ze schalen wanneer ze in een document worden ingevoegd tot juiste maat(de originele kopie blijft ook bewaard), voeg een kader toe, rond de randen.

Verduidelijken heeft basisgereedschappen werken met afbeeldingen en tekst. Zo kunnen afbeeldingen worden gedraaid, bijgesneden, tekstinscripties of opmerkingen, pijlen, rechthoeken en andere worden eraan toegevoegd. grafische objecten, wat handig kan zijn voor visuele selectie van gebieden in de schermafbeelding.

Als u met tekst werkt, kunt u genummerde en lijsten met opsommingstekens, code invoegen, hyperlinks, inspringen. Voor sommige talen werkt grammaticacontrole terwijl u typt, er is een zoekopdracht en vervanging van gegevens in het document.

U kunt met andere gebruikers samenwerken aan Clarify-projecten. Hiervoor dient u een account aan te maken op de Clarify-it.com website. Bovendien ondersteunt het programma Dropbox- en Evernote-services, waardoor het mogelijk is om projecten te exporteren naar PDF-, Word-, HTML- en WordPress-sites. Indien gewenst kunt u ook eenvoudig de volledige tekst van het document (of tekst met afbeeldingen) naar het klembord kopiëren.

Bij het exporteren kunt u een ontwerpthema kiezen, kop- en voetteksten toevoegen en verschillende weergave-opties beheren (afhankelijk van het formaat). Er zijn bijvoorbeeld drie thema's beschikbaar voor export naar Word en het voltooide document wordt gepresenteerd als een perfect opgemaakt bestand, met stijlen, koppen, lijsten, hyperlinks. Dit is een plezier om mee te werken, vooral als u zich herinnert hoeveel tijd u handmatig aan dergelijke opmaak in Word moet besteden.

Ook interessant is de functie om alle screenshots naar een map te exporteren. Tegelijkertijd slaat Clarify alle afbeeldingen die in het document worden gebruikt op in een bepaalde map en geeft elk bestand een naam die overeenkomt met de titel van de sectie waaraan het is gekoppeld.

⇡ dr.Explain 5.3 - semi-automatische handleidingen met kant-en-klare annotaties

• Ontwikkelaar: Indigo Byte Systems.
• Distributie: shareware, vanaf 7.500 roebel.
• Russische interface: ja.

Dr.Explain kan daar niet op opscheppen moderne interface, zoals Clarify, maar dit programma heeft zijn eigen unieke eigenschappen. Misschien wel het belangrijkste is de automatisering van het proces van het maken van technische documentatie. Specificeer gewoon het toepassingsvenster of de webpagina van de service die u wilt beschrijven, en Dr.Explain zal een screenshot maken, alle interface-elementen analyseren, callouts toevoegen en ze zelfs waar mogelijk labelen.

Als een menu wordt aangetroffen in de interface van de vastgelegde toepassing, zal Dr.Explain het zeker uitbreiden, een momentopname maken van alle niveaus van het submenu en toelichtingen toevoegen voor elk element. Bovendien zullen alle schermafbeeldingen in het Dr.Explain-project worden geplaatst met behoud van de documentstructuur (dat wil zeggen, het hoofdvenster bevindt zich in sectie 1, het uitgevouwen menu is 1.1 en de submenu-items zullen 1.1.1 zijn, 1.1.2, enzovoort). Zo wordt al het saaie en eentonige werk gedaan in automatische modus, en de gebruiker hoeft alleen een beschrijving van alle interface-elementen toe te voegen. Het is duidelijk dat de structuur van het document kan worden gewijzigd door alinea's te verplaatsen, nieuwe toe te voegen en overbodige te verwijderen.

Zelfs voordat u schermafbeeldingen maakt, kunt u veel opties configureren die betrekking hebben op afbeeldingen. Het is bijvoorbeeld mogelijk om de locatie van toelichtingen, de annotatiestijl in te stellen, de optie te bepalen voor het genereren van bestandsnamen (volgens sectiekoppen of hun nummers).

Als u eerder in een andere applicatie aan documentatie heeft gewerkt, kunt u het project en programma eenvoudig importeren. Dr.Explain ondersteunt de import van CHM-, Word-, HTML-, HLP-, RTF-, TXT- en XML-documenten.

Samenwerking aan documentatie wordt georganiseerd via de Tiwri.com-service, die speciaal is gemaakt voor gegevensuitwisseling tussen Dr.Explain-gebruikers. Vanuit het programmavenster kunt u het huidige project naar de server uploaden, wijzigingen verzenden, bewerkingen resetten en de geschiedenis volgen.

Kant-en-klare documentatie kan worden geëxporteerd in CHM-, Word-, HTML- en PDF-formaten. In dit geval kunt u, zelfs vóór de export, zien hoe de handleiding eruit zal zien in een van deze formaten. Vergeet voor het exporteren niet naar de projectinstellingen te gaan en in te stellen Extra opties. Als u bijvoorbeeld een document opslaat als PDF, kunt u trefwoorden, auteur, titel, onderwerp en formaat opgeven, kop- en voetteksten en paginanummering instellen en bladwijzers voor secties maken. Bij het exporteren naar HTML is het mogelijk om een ​​sitemap op te zetten, opmerkingen toe te voegen voor Facebook- en Disqus-gebruikers, de weergave van een paneel met sociale netwerkknoppen in te schakelen, de gegevens op te geven van de FTP-server waarnaar het project zal worden geüpload.

Ten slotte moet u erop letten dat Dr.Explain een product is van binnenlandse ontwikkelaars, dus het is vrij te verwachten dat u deze kunt vinden volledige ondersteuning Russische taal.

⇡ Manula - overdracht van handleidingen online

• Ontwikkelaar: Bitz & Pixelz.
• Besturingssysteem: elk.
• Distributie: via abonnement (vanaf $10 per maand).
• Russische interface: nee.

Begin 2009 besloot Alwin Hoogerdijk, de maker van de Collectorz.com-familie van toepassingen voor het volgen van collecties, om online hulp voor zijn programma's te creëren. Hij had er genoeg van dat hij vaak de release van nieuwe versies van programma's moest uitstellen omdat wijzigingen in de gebruikersdocumentatie nog niet klaar waren, of juist nieuwe releases beschikbaar moest stellen om te downloaden met verouderde helpbestanden, en breng vervolgens nieuwe builds uit die alleen handleidingen hebben bijgewerkt.

Om het proces van het toevoegen van documentatie gemakkelijker te maken voor ontwikkelaars en sneller voor gebruikers om toegang te krijgen, wilde Alvin alles online zetten. Hij ging op zoek naar een gespecialiseerd contentmanagementsysteem voor het maken van technische documentatie. En toen bleek dat zoiets niet bestaat, creëerde de ontwikkelaar eigen systeem voor uw toepassingsfamilie. Het werd later ontwikkeld tot het meer veelzijdige commerciële product Manula.com.

Manula.com geeft je de mogelijkheid om handleidingen te maken en bij te werken in je browser, zonder dat je een desktop applicatie nodig hebt. Het grote voordeel van de online handleiding is de instant update. Zodra de ontwikkelaars er wijzigingen in hebben aangebracht, zijn de bijgewerkte helpbestanden al beschikbaar voor gebruikers - het is niet nodig om ergens iets te exporteren, HTML-bestanden naar de server te uploaden, enzovoort. Tegelijkertijd zien handleidingen er op elk apparaat even goed uit - op grote monitoren, tablets of smartphones. De dienst past zich automatisch aan de schermgrootte aan.

En als de gebruiker een kopie van de handleiding wil hebben om offline te bekijken, is dat helemaal niet moeilijk. Manula biedt een handige download van handleidingen die op zijn platform zijn gemaakt in PDF-formaat.

Manula heeft ook ingebouwde tools om wijzigingen bij te houden en feedback van gebruikers te krijgen. Ze worden aangemoedigd om geselecteerde onderwerpen in de referentiedocumentatie te beoordelen. Voor ontwikkelaars zijn er visuele statistieken van beoordelingen en het aantal bezoeken verschillende secties handmatig. Hierdoor kunt u altijd zien waar de handleiding moet worden gefinaliseerd, gedetailleerder of gekoppeld aan andere secties.

Handleidingen die met Manula zijn gemaakt, hebben een geïntegreerd zoeksysteem dat rekening houdt met sectietitels, documentatie-inhoud en trefwoorden die door de ontwikkelaar zijn opgegeven. De service slaat de geschiedenis van zoekopdrachten op en toont ontwikkelaars populaire zoekopdrachten, zodat u gemakkelijk titels en trefwoorden kunt bewerken.

Een van de interessante functies Manula is een functie voor het delen van onderwerpen. Als een bedrijf meerdere producten van hetzelfde type heeft, kunnen individuele hulpfragmenten voor hen gemeenschappelijk worden gemaakt. Het belangrijkste verschil met eenvoudige kopie Kant-en-klare documentatiefragmenten is dat wanneer u de functie voor delen van onderwerpen gebruikt, u slechts op één plaats wijzigingen hoeft aan te brengen. Tegelijkertijd wordt de documentatie in alle toepassingen automatisch bijgewerkt. Om het proces verder te automatiseren, helpen variabelen (bijv. (APPNAME)), die voor elke gebruikershandleiding afzonderlijk worden geconfigureerd, het proces te automatiseren.

Algemene Help-fragmenten kunnen ook worden gebruikt om aparte documentatie te maken voor: verschillende versies toepassingen. Om ervoor te zorgen dat gebruikers geen tijd verspillen aan het zoeken naar functies die ze niet hebben, kunt u voor elke versie aparte handleidingen maken. In dit geval wordt het grootste deel van de help beheerd met behulp van de functie voor delen van onderwerpen.

Er is geen ingebouwde tool voor het maken van schermafbeeldingen in Manula - u moet kant-en-klare afbeeldingen uploaden naar de afbeeldingenbibliotheek (dit is gebruikelijk voor alle projecten) en deze vervolgens op de juiste plaatsen in de documentatie invoegen. Het toevoegen van tekst gebeurt ook in de online editor, en hier konden de ontwikkelaars van de dienst iets interessants bedenken. Samen met het gebruik van visuele editor het wordt aanbevolen om met textielcodes te werken om het opmaakproces te versnellen. Deze codes maken het mogelijk om tekst op te maken zonder de editor-knoppen te gebruiken. Als de tekst bijvoorbeeld moet worden gemarkeerd, hoeft deze alleen maar tussen twee asterisken (*zoals deze*) te staan, en om een ​​kop op het eerste niveau te maken, volstaat het om h1- aan het begin van de regel te schrijven.

⇡ StepShot - schieten, arrangeren en ondertekenen

• Ontwikkelaar: StepShot.
• Besturingssysteem: Windows.
• Distributie: Per abonnement ($ 29 per maand). Er is een volledig functionele proefversie voor 14 dagen, die dan beperkt wordt.
• Russische interface: nee.

Bijna elke gebruikershandleiding bevat noodzakelijkerwijs instructies die uitleggen welke stappen moeten worden genomen om het gewenste resultaat te bereiken. Het lezen van dergelijke handleidingen, waarbij elke stap vergezeld gaat van een screenshot en een uitleg, is een plezier, maar het maken ervan duurt vaak lange uren. Sommige technisch schrijvers schrijven eerst de tekst en maken daarna alle screenshots en plakken ze op de juiste plekken, anderen geven er de voorkeur aan om screenshots één voor één te maken, in de handleiding te plakken en meteen een beschrijving toe te voegen. Het blijkt in ieder geval behoorlijk arbeidsintensief.

StepShot is een geweldig programma dat helpt om het maken aanzienlijk te versnellen stap voor stap instructies. Het helpt je snel alle schermafbeeldingen te maken zonder afgeleid te worden door ze op te slaan en te plakken, ze in de juiste volgorde te rangschikken, je te helpen een beschrijving en annotaties toe te voegen en ze vervolgens te publiceren in een van de populaire formaten.

Werken in StepShot is gebouwd in de vorm van een wizard. U moet een nieuw project maken en vervolgens het vastlegproces starten en beginnen met het uitvoeren van de acties die onderhevig zijn aan documentatie. Met elke muisklik maakt het programma een screenshot en slaat het op. Tegelijkertijd is het StepShot-paneel constant op het scherm, waarmee u het opnameproces kunt stoppen en de screenshot-modus kunt wijzigen (volledig scherm, actief venster, geselecteerd rechthoekig gebied).

Dit paneel is natuurlijk niet zichtbaar in de screenshots. Afhankelijk van de instellingen kan het vastleggen alleen plaatsvinden wanneer er wordt geklikt terwijl CTRL (of een andere handige toets) wordt ingedrukt, of omgekeerd, in alle gevallen behalve wanneer de gebruiker de opgegeven toets ingedrukt houdt. In de programma-instellingen kun je ook een vertraging instellen tussen klikken en het maken van een screenshot.

Wanneer het proces voor het maken van instructies is voltooid, worden alle ontvangen afbeeldingen geopend in het StepShot-venster. Aan de linkerkant is een navigatiebalk met afbeeldingsminiaturen, aan de rechterkant is een screenshot waar je aan werkt, evenals een gebied voor het toevoegen van een beschrijving. De schermafbeeldingen zijn al gerangschikt in de volgorde waarin ze zijn gemaakt, maar kunnen indien nodig opnieuw worden gerangschikt door ze te slepen en neer te zetten. Daarnaast kan elke stap (een screenshot met een beschrijving) worden gekopieerd of verwijderd, evenals een lege stap ervoor worden toegevoegd, waarvoor bijvoorbeeld een afbeelding van schijf kan worden geïmporteerd.

Als de instructie omvangrijk is, is het logisch om deze in secties op te splitsen en op de juiste plaatsen scheidingstekens toe te voegen. Voor elke sectie is het mogelijk om een ​​titel in te stellen. Op basis van de paragrafen wordt automatisch een inhoudsopgave gegenereerd, die aan het begin van de handleiding staat.

Meestal wordt er bij het maken van handleidingen veel tijd besteed aan het markeren van het gebied waar de cursor zich in de schermafbeelding bevindt (meestal de plaats waar u wilt klikken). StepShot maakt het ook mogelijk om dit te automatiseren routinematige actie. Het aangeklikte interface-element kan automatisch worden gemarkeerd met een rode rechthoek of een gele cirkel. Bovendien kan het programma automatisch de randen van schermafbeeldingen gladstrijken.

In het stadium van het bewerken van de ontvangen screenshots - al in handmatige modus- u kunt pijlen, toelichtingen of andere toevoegen grafische elementen en markeer bepaalde delen van de afbeelding met kleur. En als u de aandacht van de lezer op meerdere gebieden in één schermafbeelding wilt vestigen, kunt u de tool Volgorde gebruiken. Dit creëert regels met cijfers aan het einde. Het is voldoende om ze op de juiste plaatsen in de afbeelding te plaatsen en een beschrijving toe te voegen.

Ook het toevoegen van beschrijvingen is zo geautomatiseerd mogelijk. Aangezien dezelfde zinnen het vaakst worden gebruikt bij het schrijven van technische documentatie, biedt het programma schermafbeeldingen met beschrijvingen zoals "Klik op de "Skype"-knop". Om dit te doen, legt het de namen van interface-elementen vast, herkent ze en voegt ze vervolgens toe aan het bijschrift onder de afbeelding. Dit werkt echter alleen voor Engels en een aantal andere Europese talen, en de samenstellers van Russischtalige documentatie zullen alle beschrijvingen handmatig moeten toevoegen.

De opmaakopties in StepShop zijn eenvoudig - u kunt de lettergrootte voor titels en beschrijvingen van schermafbeeldingen wijzigen, tekst vet, cursief of onderstreept maken, inspringen regelen en hyperlinks invoegen. Vergeet niet dat u een beschrijving en een auteur kunt toevoegen voordat u een project exporteert.

Nadat u uw handleiding hebt voltooid, kunt u deze exporteren naar een van de verschillende ondersteunde indelingen: word document, PDF, HTML, DITA of XML. Er zijn echter verschillende sjablonen beschikbaar voor Word.

Er is ook directe publicatie naar Wordpress en Confluence, en er wordt voorgesteld om alle afbeeldingen die in het project worden gebruikt in één map op te slaan. Helaas kunt u in dit geval alleen de kwaliteit van de foto's controleren, maar u kunt de namen niet wijzigen. Screenshots worden opgeslagen met namen als image0001.jpg, image0002.jpg, wat niet altijd handig is (het zou fijn zijn als het mogelijk zou zijn om afbeeldingen een naam te geven op basis van titels in het project).

Ondanks het feit dat StepShot tegen betaling wordt gedistribueerd, kunt u gratis met het programma werken, als u bereid bent een watermerk op de resulterende afbeeldingen te plaatsen. Daarnaast, gratis versie stelt u in staat om maximaal vijf exporteerbare projecten per maand te maken.

⇡ iorad - analoogStepShot maar in browser

• Ontwikkelaar: iorad inc.
• Besturingssysteem: elk.
• Distributie: Per abonnement ($ 90 per maand). Er is een beperkte gratis versie.
• Russische interface: nee.

Om met iorad aan de slag te gaan, moet u de Google Chrome-extensie installeren en een webpagina openen waarvan de acties moeten worden gedocumenteerd. Daarna moet de auteur op de extensieknop klikken. De iorad-webservice gebruikt dezelfde aanpak als in StepShot (de auteur van de instructie voert alle acties uit, de service slaat ze op, verdeelt ze in stappen, die vervolgens kunnen worden bewerkt en gepubliceerd als een les). Iorad werkt echter als een browserextensie en alle verwerking, bewerking en publicatie van stapsgewijze instructies wordt uitgevoerd op de server. Aan de ene kant is dit handig, omdat de service op elk platform beschikbaar is, maar er is een vervelende beperking - met iorad kun je alleen acties opnemen die in de browser worden uitgevoerd. Dat wil zeggen, de service is alleen geschikt voor het maken van handleidingen voor webapplicaties, en voor: desktopprogramma's niet goed.

Eenmaal ingedrukt, geeft iorad je drie seconden om je voor te bereiden, waarna de opname begint. De service herkent en slaat elke actie op - muisklik, dubbelklik, scrollen in het venster, typen, enzovoort. Wanneer de instructie-opname is voltooid, hoeft u alleen maar op de extensieknop op de . te drukken chromen panelen. Het proces kan ook een tijdje worden onderbroken en vervolgens worden hervat.

Wanneer de opname is voltooid, herstelt iorad alle gebruikersacties en verdeelt de instructie in stappen. Alle interface-elementen die zijn ingeschakeld, worden gemarkeerd (bijvoorbeeld een knop waarop moet worden geklikt). Bovendien voegt iorad automatisch eenvoudige tekstinstructies toe voor elke stap.

Elke les begint met de zin "De eerste stap is om [naam webpagina] te openen" en eindigt met de zin "Dat is het". Je bent klaar." Ondanks het feit dat beschrijvingen automatisch alleen in het Engels worden gegenereerd, is het in de voltooide instructie mogelijk om ze in andere talen te zien vanwege integratie met Google vertaler. Als je geen lange beschrijvingen toevoegt, maar je beperkt tot eenvoudige zinnen, werkt zo'n vertaling acceptabel.

Als u echter wat tijd besteedt, kunt u meteen een beschrijving in uw moedertaal toevoegen. Houd er echter rekening mee dat de lengte van de beschrijving beperkt is tot 250 tekens. Het kan gebruiken verschillende varianten lettertypestijlen en hyperlinks. Bovendien kunt u voor elke stap een audio-instructie van maximaal één minuut toevoegen. Het kan direct worden opgenomen in de webapplicatie-interface of worden gedownload van bestanden die beschikbaar zijn op de computer.

Wat de tools voor het bewerken van screenshots betreft, hebben de makers van iorad nog veel werk te doen. De gebruiker kan alleen een deel van de afbeelding vervagen en de grootte en locatie van het selectiekader wijzigen.

Klaar instructies kunnen worden opgeslagen als Word-bestanden Doc, PowerPoint en PDF, maar ook ingebed in websites of bekeken in een browser op elk platform, zowel desktop als mobiel. Als u de laatste twee opties gebruikt, kunt u het belangrijkste voordeel van iorad waarderen - interactiviteit. De instructie die met behulp van de service is ontvangen, wordt gelanceerd in een speciale speler. De gebruiker kan een van de opties kiezen om ermee te werken: bekijken of zelfstandig alle stappen herhalen.

In het eerste geval worden alle screenshots en beschrijvingen ervan op één pagina weergegeven en kunt u eenvoudig lezen wat u moet doen. In het tweede geval wordt de gebruiker gevraagd om alle acties van de auteur te herhalen om het volgende te bereiken: gewenste resultaat. Dat wil zeggen, hij leest de beschrijving voor de schermafbeelding, voert de actie uit en gaat dan pas door naar de volgende stap. Perfecte oplossing om ervoor te zorgen dat de gebruiker echt begrijpt wat hij moet doen.

⇡ Conclusie

Gespecialiseerde programma's voor het maken van handleidingen kunnen het maken van technische documentatie aanzienlijk versnellen. Hoe duidelijk, gedetailleerd en gestructureerd het helpbestand zal zijn, hangt echter volledig af van de compilers.

Bij het werken aan documentatie moet u altijd rekening houden met het "Goldilocks-principe": de gebruiker moet niet te veel informatie krijgen, niet te weinig, maar precies zoveel als nodig is om taken uit te voeren. Goede documentatie zou moeten werken als een navigator: zodra de gebruiker heeft laten zien waar hij is (welk probleem hij is tegengekomen), moet hij onmiddellijk het helpbestand gebruiken om de goede weg(oplossing voor het probleem). En vergeet natuurlijk de hyperlinks niet, waarmee u het vrije verkeer van de gebruiker door de handleiding moet verzekeren. Als in zijn handen gedetailleerde PDF 100 pagina's lang zonder referenties, de kwaliteit van dergelijke documentatie kan nauwelijks worden beoordeeld door iemand anders dan de maker ervan.

Moderne tools voor het maken van helpgidsen zijn echter zo divers en multifunctioneel dat het niet moeilijk is om met hun hulp gedetailleerde, begrijpelijke en goed ontworpen documentatie te maken.

Je zal nodig hebben

• - 100% kennis van het apparaat of softwareproduct waarvoor de handleiding wordt geschreven;
• - kennis op het gebied van taalkunde;
• - schrijfvaardigheden.

Instructie

Beheer gebruiker of, met andere woorden, een instructiehandleiding - een document dat is ontworpen om hulp te bieden bij het gebruik van een bepaald systeem van zijn gebruiker m. Een gids samenstellen gebruiker je moet het systeem dat wordt beschreven honderd procent kennen, maar bekijk het met de ogen van een onwetende. Stel dat leiderschap gebruiker Voor sommigen softwarehulpprogramma, die nog geen analogen heeft. Stel je voor dat je dit programma voor het eerst tegenkomt. Waar te beginnen? Wat moet je eerst weten? Organiseer deze kennis door deze op te splitsen in belangrijke categorieën.

Nadat je alle informatie over je creatie in groepen hebt verdeeld, heb je een plan gemaakt voor het schrijven van een gids gebruiker. Begin met het beschrijven van hoe uw programma werkt vanaf de basis, en laat de meest complexe details voor het laatst, zoals het herprogrammeren van functies of het werken met kritieke fouten. Op dit punt zou u de inhoud van de gids gereed moeten hebben. gebruiker is een van de verplichte onderdelen van dit document.

Als de handleiding die u aan het maken bent, bedoeld is voor gebruik in een groot bedrijf, moet u aandacht besteden aan de bedrijfsnormen die daar worden gehanteerd. Bijvoorbeeld in veel Russische bedrijven gebruikershandleidingen worden niet geaccepteerd zonder illustratieve begeleiding, met andere woorden, afbeeldingen die uitleggen wat er staat. In de gids gebruiker naast de inhoud moeten er nog andere verplichte onderdelen zijn: - Annotatie, dat wil zeggen een uitleg veel voorkomende taken handleiding en het product dat wordt beschreven; - een inleiding waarin wordt gesproken over gerelateerd aan de handleiding gebruiker documenten en methoden voor het gebruik van de handleiding; - secties waarin het gebruik van het product in verschillende stadia van gebruik wordt uitgelegd, bijvoorbeeld eerste stappen, reparatie of onderhoud; - een sectie met veelgestelde vragen en antwoorden daarop; - een woordenlijst of .

Meestal door een handleiding te maken gebruiker er wordt een technisch schrijver ingeschakeld - een persoon die over alle benodigde kennis beschikt, zowel in de taal als in het product dat wordt beschreven. Wanneer u zich bezighoudt met de activiteit van een technisch schrijver zonder de juiste training, moet u een paar regels onthouden. Ten eerste mag men geen misbruik maken van speciale termen die niet duidelijk zijn voor de gewone man gebruiker. Ten tweede moet elke gebruikte term gedetailleerd en uitgelegd worden. Ten derde moet je zo duidelijk en beknopt mogelijk schrijven. Ten slotte moet een technisch schrijver naar zijn eigen tekst kunnen kijken door de ogen van een particulier gebruiker om de tekortkomingen van uw eigen tekst te zien.

Geef in de Bronnen die worden gebruikt in de sectie Ontwikkeling een lijst aan van wetenschappelijke en technische publicaties, regelgevende en technische documenten en ander wetenschappelijk en technisch materiaal waarnaar in de originele tekst wordt verwezen.

De toelichting is opgesteld door professionals op het gebied van softwareontwikkeling en voor specialisten van hetzelfde vaardigheidsniveau. Daarom is het aangewezen om speciale terminologie te gebruiken, naar speciale literatuur te verwijzen, enz.

11.3. Gebruikershandleiding

Zoals hierboven vermeld, wordt momenteel vaak een ander operationeel document gebruikt, dat deels de begeleiding van de systeemprogrammeur, programmeur en operator omvat. Dit document wordt de Gebruikershandleiding genoemd. Het verschijnen van een dergelijk document was een gevolg van het wijdverbreide gebruik van personal computers, waarbij gebruikers de drie aangegeven specialisten in hun persoon combineren.

Het samenstellen van documentatie voor gebruikers heeft zijn eigen kenmerken omdat de gebruiker in de regel geen professional is op het gebied van softwareontwikkeling. Het boek van S.J. Grimm geeft richtlijnen voor het schrijven van dergelijke softwaredocumentatie:

houd rekening met de belangen van gebruikers - de handleiding moet alle instructies bevatten die nodig zijn voor de gebruiker;

geef duidelijk aan, gebruik korte zinnen;

vermijd technisch jargon en zeer technische terminologie, als u nog enkele termen moet gebruiken, dan moeten ze worden uitgelegd;

wees precies en rationeel - meestal leest niemand lange en verwarrende handleidingen, het is bijvoorbeeld beter een tekening van een vorm te geven dan deze lang te beschrijven.

De gebruikershandleiding bevat meestal de volgende secties:

algemene informatie over het softwareproduct;

beschrijving van de installatie;

lancering beschrijving;

gebruiksaanwijzing (of beschrijving gebruikersinterface);

berichten aan de gebruiker.

Hoofdstuk Algemene informatie Over het programma bevat meestal de naam van het softwareproduct, korte beschrijving zijn functies, geïmplementeerde methoden en mogelijke toepassingen.

Het gedeelte Installatie bevat meestal: gedetailleerde beschrijving acties om het softwareproduct te installeren en berichten die kunnen worden ontvangen.

De sectie Start beschrijft meestal de stappen om het softwareproduct te starten en de berichten die kunnen worden ontvangen.

Hoofdstuk Handleiding bevat meestal een beschrijving van de bedrijfsmodi, invoer-/uitvoerinformatieformaten en mogelijke instellingen.

Hoofdstuk Berichten aan de gebruiker moet een lijst bevatten mogelijke berichten, een beschrijving van hun inhoud en de acties die op deze berichten moeten worden ondernomen.

11.4. Handleiding voor systeemprogrammeur

Volgens GOST 19.503-79 moet de handleiding van de systeemprogrammeur alle informatie bevatten die nodig is om de software te installeren, configureren en de prestaties te testen. Bovendien bevat het, zoals hierboven vermeld, vaak een beschrijving van het vereiste onderhoud, dat eerder werd gegeven in de bedieningshandleiding (GOST 19.505-79) en/of onderhoudshandleiding (GOST 19.508-79). Momenteel dit schema gebruikt om een ​​systeembeheerdershandleiding samen te stellen.

De System Programmer's Guide zou de volgende secties moeten bevatten:

Algemene informatie over het softwareproduct,

structuur,

instelling,

inspectie,

extra functies,

berichten naar de systeemprogrammeur.

De sectie Algemene informatie over het programma moet een beschrijving bevatten van het doel en de functies van het programma, evenals informatie over de technische en softwaretools die zorgen voor de uitvoering van dit programma (bijvoorbeeld de hoeveelheid RAM, vereisten voor de samenstelling en parameters van externe apparaten, softwarevereisten, enz.).

In sectie Programma structuur informatie over de opzet van het programma moet worden gegeven,

haar componenten, koppelingen tussen componenten en koppelingen naar andere programma's.

In de paragraaf Opstellen van het programma dient een beschrijving te worden gegeven van de stappen voor het instellen van het programma voor de gebruiksvoorwaarden.

In het gedeelte Programmaverificatie moet worden beschreven hoe het programma werkt, zoals testcases.

In sectie Extra functies er moet een beschrijving worden gegeven van extra functies van het programma en manieren om er toegang toe te krijgen.

In sectie Berichten aan de systeemprogrammeur de teksten van berichten die zijn uitgegeven tijdens de configuratie en verificatie van het programma, evenals tijdens de uitvoering ervan, moeten een beschrijving van hun inhoud en acties die op deze berichten moeten worden ondernomen, worden vermeld.

11.5. Basisregels voor het ontwerpen van programmadocumentatie

Bij het ontwerpen van tekst en grafisch materiaal dat is opgenomen in de programmadocumentatie, moeten de huidige normen worden gevolgd. Enkele van deze normen staan ​​hieronder vermeld.

Tekst opmaken en grafisch materiaal. Tekstdocumenten worden opgemaakt op A4-vellen en grafisch obscene documenten mogen op A3-vellen worden gepresenteerd. De marges op het vel worden bepaald volgens de algemene eisen: links - minimaal 30, rechts - minimaal 10, boven - minimaal 15 en onder - minimaal 20 mm. In teksteditors voor notitieontwerp worden paginaparameters gerangschikt afhankelijk van het afdrukapparaat. Bij het handmatig voorbereiden van documenten worden pagina-instellingen gekozen voor het gemak.

De nummering van alle pagina's is doorlopend. Het nummer is in Arabische cijfers rechtsboven aangebracht. Pagina's worden beschouwd als bladen met teksten en tekeningen, evenals als toepassingsbladen. De titelpagina wordt beschouwd als de eerste pagina. Het paginanummer op de titelpagina is niet aangebracht.

Sectienamen worden in hoofdletters in het midden van de regel geschreven. De afstand tussen kopteksten en tekst, evenals tussen kopteksten en subsecties, moet gelijk zijn aan:

bij het uitvoeren van een document op een getypte manier - twee intervallen;

wanneer uitgevoerd op een handgeschreven manier - 10 mm;

gebruik makend van tekstverwerkers- bepaald door de mogelijkheden van de redacteur. De namen van subsecties en alinea's moeten worden geplaatst met alinea inspringen en printen

onderstreept met een hoofdletter, zonder onderstreping en zonder punt aan het einde. De afstand tussen de laatste regel van de tekst van de vorige sectie en de volgende kop, indien geplaatst op één pagina, moet gelijk zijn aan:

bij het uitvoeren van een document op een getypte manier - drie intervallen;

indien met de hand uitgevoerd - minimaal 15 mm;

bij het gebruik van teksteditors wordt dit bepaald door de mogelijkheden van de editor.

Secties en subsecties zijn genummerd met Arabische cijfers met een punt. Secties moeten worden genummerd 1,2, enz. Het sectienummer omvat het sectienummer en serienummer onderafdeling opgenomen in deze sectie, gescheiden door een punt. Bijvoorbeeld: 2.1, 3.5. Verwijzingen naar paragrafen, paragrafen en subparagrafen geven, met gebruikmaking van het volgnummer van de paragraaf of paragraaf, op-

bijvoorbeeld "in sec. 4", "in artikel 3.3.4".

De tekst van de paragrafen wordt afgedrukt met tussenpozen van 1,5-2. Bij gebruik van teksteditors moet de hoogte van letters en cijfers minimaal 1,8 mm zijn (lettertypen nr. 11-12).

Opsommingen moeten worden genummerd met Arabische cijfers met haakjes, bijvoorbeeld: 2), 3), enz. - met een alinea-inspringing. Het is toegestaan ​​om de opsomming te markeren door een koppelteken voor een tekstitem te plaatsen of een teken dat het vervangt in teksteditors.

Ontwerp van tekeningen, schema's van algoritmen, tabellen en formules. In overeenstemming met GOST 2.105-79 "Algemene vereisten voor tekstdocumenten", kunnen illustraties (grafieken, diagrammen, diagrammen) zowel in de hoofdtekst als in de bijlage worden gegeven. Alle illustraties worden tekeningen genoemd. Alle figuren, tabellen en formules zijn doorlopend genummerd in Arabische cijfers ( end-to-end nummering) of binnen een sectie (relatieve nummering). In de applicatie - binnen de applicatie.

Elke figuur moet een bijschrift hebben - een titel die onder de figuur wordt geplaatst, bijvoorbeeld:

Afb.12. Hoofdmenu Venstervorm

Er moet naar alle figuren, tabellen en formules in de notitie worden verwezen in de vorm: "(Fig. 12)" of "de vorm van het hoofdmenuvenster wordt getoond in fig. 12".

Indien de ruimte het toelaat, dienen figuren en tabellen direct na de alinea waarin ze voor het eerst worden genoemd, of zo dicht mogelijk bij die alinea op de volgende pagina's te worden geplaatst.

Als de figuur meer dan één pagina beslaat, worden op alle pagina's behalve de eerste het nummer van de figuur en het woord "Vervolg" genoteerd. Bijvoorbeeld:

Rijst. 12. Vervolg

Cijfers moeten zo worden geplaatst dat ze kunnen worden bekeken zonder de pagina om te slaan. Als deze plaatsing niet mogelijk is, moeten de figuren zo worden gerangschikt dat de pagina met de klok mee moet worden gedraaid om te bekijken. In dit geval is de bovenrand de linkerrand van de pagina. De locatie en grootte van de velden blijven behouden.

Algoritmeschema's moeten worden gemaakt in overeenstemming met de UEA-standaard. De dikte van een ononderbroken lijn bij het tekenen van schema's van algoritmen moet van 0,6 ... 1,5 mm zijn. De opschriften op de schema's moeten in tekeningtype zijn gemaakt, de hoogte van letters en cijfers moet minimaal 3,5 mm zijn.

Het tafelnummer is aan de rechterkant geplaatst bovenhoek of vóór de tabelkop, als die er is. De kop, behalve de eerste letter, is in kleine letters.

De testresultaten worden gegeven in de tabel. 4.

Het formulenummer wordt gezet met rechter zijde pagina's tussen haakjes op formuleniveau. Bijvoorbeeld:

Ontwerpen van applicaties. Elke aanvraag moet beginnen op een nieuwe pagina met het woord "APPENDIX" in hoofdletters in de rechterhoek en een thematische kop hebben. Als er meer dan één aanvraag is, zijn ze allemaal genummerd met Arabische cijfers: BIJLAGE 1, BIJLAGE 2, enz. Bijvoorbeeld:

BIJLAGE 2

Titelpagina van de schikking en toelichting

Cijfers en tabellen die in de applicatie worden geplaatst, zijn binnen elke applicatie genummerd in Arabische cijfers met de toevoeging van de letter "P". Bijvoorbeeld:

Rijst. P. 12 - 12e tekening van de aanvraag; Rijst. Sh.2 - 2e tekening van de 1e aanvraag.

Als de applicatie de tekst van het programma bevat, wordt elk bestand als een afbeelding opgemaakt met de naam van het bestand en het doel ervan, bijvoorbeeld:

Rijst. P2.4. Het menuran.pas-bestand is het programma om de cursor van het hoofdmenu te verplaatsen.

Het maken van een lijst met referenties. De lijst met referenties moet alle gebruikte bronnen bevatten. Informatie over boeken (monografieën, studieboeken, handleidingen, naslagwerken, etc.) dient te bevatten: de achternaam en voorletters van de auteur, titel van het boek, plaats van uitgave, uitgeverij, jaar van uitgave. Als er drie of meer auteurs zijn, is het toegestaan ​​om de achternaam en voorletters van alleen de eerste van hen aan te geven met de woorden "et al.". De uitgeverij moet volledig worden vermeld in de nominatief: er kunnen slechts twee steden worden afgekort: Moskou (M.) en St. Petersburg

Informatie over een artikel uit een tijdschrift dient te omvatten: de achternaam en voorletters van de auteur, de naam van het artikel, editie (tijdschrift), serie (indien aanwezig), jaar van uitgave, volume (indien aanwezig), nummer van uitgave (tijdschrift) ) en paginanummers waarop het artikel.

11.6. Regels voor het opstellen van een afrekening en toelichting bij de cursusopzet

Bij het opstellen van toelichtingen dient men zich te houden aan GOST 7.32-91 (ISO 596682) "Onderzoeksrapport. Structuur en registratieregels. In overeenstemming met deze norm moet een tekstdocument van dit type het volgende bevatten:

titelpagina,

essay,

inhoud,

invoering,

het belangrijkste deel

conclusie,

lijst van gebruikte bronnen, inclusief literatuur,

toepassingen.

De titelpagina is opgesteld in overeenstemming met GOST 19.104-78 "Eengemaakt systeem van programmadocumentatie. Hoofdinscripties "(Fig. 11.1).

De tweede pagina is een abstract of annotatie op de ontwikkelde software. De samenvatting in verkorte vorm moet informatie bevatten over de omvang van het document, het aantal illustraties, toepassingstabellen, enz., evenals een lijst trefwoorden en belangrijkste bepalingen van het document. Bijvoorbeeld voor een onderzoeksrapport: een beschrijving van het object van onderzoek, doelstellingen van het werk, onderzoeksmethoden en apparatuur, verkregen resultaten, aanbevelingen voor implementatie, enz. De annotatie beschrijft ook kort het doel en de kenmerken van de ontwikkeling, maar het bevat meestal geen volume-informatie, enz.

Derde pagina - inhoud, inclusief: inleiding, titels van alle secties, subsecties, paragrafen, conclusie, bibliografie en bijlagen met paginanummers. Noch het abstract, noch het abstract, noch de zelfinhoud wordt in de inhoudsopgave genoemd.

Daarna volgen de secties van het document in de volgorde die wordt bepaald door de logica van de presentatie van het materiaal. Er kunnen meer bijlagen volgen, die materiaal bevatten dat vanwege het beperkte volume niet in het document is opgenomen, maar interessant zijn voor een dieper begrip van het gepresenteerde materiaal.

Bekijk als voorbeeld de inhoudsopgave van de toelichting bij het project voor de cursus "Programmeertechnologie".

testvragen

1. Noem de belangrijkste soorten softwaredocumentatie. Beschrijf elk van hen. In welke gevallen worden ze gebruikt?

2. Wat moet in de toelichting worden beschreven? Voor wie is het bedoeld? Hoe komt het dat een toelichting meestal niet alleen beschrijft: genomen beslissingen, maar ook afgewezen opties?

3.Voor wie is de gebruikershandleiding bedoeld? Wat moet het bevatten? In welke situaties leest u de gebruikershandleiding? Denk eens terug aan de gebruikershandleidingen die je hebt gelezen. Wat vond je niet leuk aan hen?

BIJLAGE

Systeem symbolen uniforme modelleringstaal (UML)

Unified Modeling Language UML - in feite standaard remedie beschrijvingen van projecten die zijn gemaakt met behulp van een objectgeoriënteerde benadering. Het softwareprojectmodel, zoals bedacht door de auteurs van de taal, kan omvatten: een groot aantal van diagrammen verschillende types gebruik makend van enkel systeem benamingen. De meest gebruikte diagrammen zijn:

gebruik case diagrammen of precedenten (gebruikt casusdiagrammen) - toon de belangrijkste functies van het systeem voor elk type gebruiker;

klassendiagrammen(klassendiagrammen): contextueel, beschrijvingen van interfaces en implementaties - demonstreren de onderlinge relatie van klassen;

activiteitendiagrammen(activiteitendiagrammen) - vertegenwoordigen een schema van controlestromen voor het oplossen van een bepaalde taak voor individuele acties, laat de aanwezigheid van parallelle en / of alternatieve acties toe;

interactiediagrammen(interactiediagrammen) van twee alternatieve typen:

a) sequentiediagrammen (sequentiediagrammen) - toon de tijdgeordende interactie van objecten tijdens het uitvoeren van een use case,

B) samenwerkingsdiagrammen(samenwerkingsdiagrammen) - geef dezelfde informatie als sequentiediagrammen, maar in een vorm die u in staat stelt de verantwoordelijkheden van klassen als geheel beter weer te geven;

diagrammen van objectstatus(statechart-diagrammen) - toon de toestand van het object en de voorwaarden voor overgangen van de ene toestand naar de andere;

pakket diagrammen(pakketdiagrammen) - demonstreer de verbanden tussen reeksen klassen gecombineerd in pakketten;

componentendiagrammen(componentendiagrammen) - laat zien uit welke softwarecomponenten het bestaat software en hoe deze componenten zich tot elkaar verhouden;

plaatsing diagrammen(implementatiediagrammen) - hiermee kunt u de software- en hardwarecomponenten van het systeem koppelen.

Toevoegingen aan diagrammen zijn geformaliseerde en niet-geformaliseerde tekstbeschrijvingen, commentaren en woordenboeken.

Gebruik bij het maken van deze en andere diagrammen verenigd systeem benamingen. Benamingen van diagrammen van precedenten worden gegeven in de tabel. P.1, klassen- en pakketdiagrammen - in tabel. P.2, interactiediagrammen - in tabel. P3, diagrammen van activiteiten en toestanden van het object - in tabel. P.4, schema's van componenten en plaatsing - in tabel. P.5. Indien nodig is het toegestaan ​​om de aanduidingen van sommige diagrammen op andere te gebruiken.