Du vil trenge

• - 100 % kunnskap om enheten eller programvareproduktet som håndboken er skrevet for;
• - kunnskap innen lingvistikk;
• - skriveferdigheter.

Bruksanvisning

Ledelse bruker eller, med andre ord, en bruksanvisning er et dokument som er ment å gi hjelp til å bruke et eller annet system bruker m. For å kompilere manualen bruker du trenger å kjenne systemet som beskrives hundre prosent, men se på det gjennom øynene til noen som ikke vet noe. La oss ta ledelsen bruker for et bestemt programvareverktøy som ikke har noen analoger ennå. Tenk deg at du møter dette programmet for første gang. Hvor bør du begynne? Hva trenger du å vite først? Organiser denne kunnskapen i viktige kategorier.

Ved å dele all informasjon knyttet til opprettelsen din i grupper, har du laget en plan for å skrive en manual bruker. Begynn å beskrive arbeidet i programmet ditt fra begynnelsen, og la til slutt de mest komplekse detaljene angående for eksempel omprogrammeringsmuligheter eller arbeid med kritiske feil. På dette tidspunktet bør du ha innholdet i veiledningen klar. bruker– en av de obligatoriske delene av dette dokumentet.

Hvis håndboken du lager er ment for bruk i et stort selskap, bør du være oppmerksom på bedriftsstandardene som er vedtatt der. For eksempel i mange russiske selskaper Brukermanualer godtas ikke uten illustrerende støtte, med andre ord bilder som forklarer hva som er skrevet. I manualen bruker i tillegg til innholdet, må det være andre obligatoriske deler: - Abstrakt, det vil si en forklaring av de generelle målene for manualen og produktet som beskrives; - introduksjon, som snakker om de som er relatert til manualen bruker dokumenter og hvordan man bruker håndboken; - seksjoner som forklarer bruken av produktet på forskjellige stadier av bruken, for eksempel første trinn, reparasjon eller vedlikehold; - en seksjon for vanlige spørsmål og svar på dem; - en ordliste eller .

Vanligvis ved å lage en manual bruker en teknisk skribent er en person som har all nødvendig kunnskap om både språket og produktet som beskrives. Når du deltar i aktivitetene til en teknisk forfatter uten riktig opplæring, må du huske noen få regler. For det første bør man ikke overbruke spesielle begreper som ikke er forståelige for den vanlige person. bruker. For det andre må hvert begrep som brukes beskrives og forklares i detalj. For det tredje må du skrive så klart og konsist som mulig. Til slutt må en teknisk forfatter kunne se på sitt eget forfatterskap gjennom øynene til en vanlig person. bruker for å se manglene i din egen tekst.

For mange programvareutviklere er det ingen enkel oppgave å lage teknisk dokumentasjon. Først og fremst fordi det innebærer møysommelig og kjedelig arbeid som kan vare i ukevis. For å beskrive en applikasjon, må du gå nøye gjennom funksjonene, ta mange skjermbilder, lime dem inn i Tekstdokument, legg til beskrivelser, forklaringer, infomeldinger og merknader, arbeid med strukturen...

Hva trenger du for å lage en hjelpefil? De fleste bruker PrntScr-knappen og et tekstredigeringsprogram til dette. Men faktisk kan du nekte begge deler. Det er programmer og webtjenester som mange utviklere (og til og med forfattere av teknisk dokumentasjon) rett og slett ikke er klar over eksisterer. Spesialiserte løsninger for å lage manualer, brukerveiledninger og andre lignende dokumenter kombinerer som regel en tekstredigerer med et minimumssett med funksjoner, et program for å lage skjermbilder, samt verktøy for eksport til populære dokumentformater. Dessuten gjør noen av disse programmene mesteparten av jobben for brukeren, og arrangerer uavhengig skjermbilder i ønsket rekkefølge og til og med legger til beskrivelser. La oss se på de fem mest vellykkede, etter vår mening.

⇡ Clarify 2.0.5 - hurtighåndbøker uten ekstra programvare

• Utvikler: Blue Mango Learning Systems.
• operativsystem: Windows/Mac.
• Distribusjon: shareware, $30.
• Russisk grensesnitt: nei.

I vid forstand er Clarify en lett tekstredigerer som legger til verktøy for rask opprettelse skjermbilder Denne enkle setningen skjuler imidlertid mange timers tid som kan lagres av tekniske dokumentforfattere. Med Clarify trenger du ikke hele tiden å bytte mellom to apper eller kaste bort tid på å sette inn skjermbilder – alt er på ett sted.

Programvinduet er delt inn i to deler: til venstre arbeid pågår med overskrifter, og til høyre - med innholdet i manualen. Hver overskrift kalles her et "trinn". Så snart forfatteren oppretter en ny tittel, ber programmet deg umiddelbart om å lage et skjermbilde for den og legge til tilhørende tekst. Hver ny overskrift blir automatisk nummerert, og du kan enkelt lage underoverskrifter, også nummererte. Men hvis du ikke trenger seksjonsnumre i dokumentet ditt, kan du ganske enkelt deaktivere denne funksjonen. Ved hjelp av hurtigtaster kan overskrifter raskt flyttes mellom seksjoner.

For å legge til et skjermbilde hvor som helst i dokumentasjonen, bare velg ønsket tittel og klikk på skjermbildeknappen. Hvis skjermbilder ble opprettet tidligere, kan du legge dem til dokumentet ved å spesifisere banen til dem på disken. Du kan ta et skjermbilde enten umiddelbart eller med en kort forsinkelse (opptil fem sekunder), noe som kan være praktisk hvis du trenger å ta et skjermbilde av en rullegardinmeny eller et annet grensesnittelement som ikke alltid vises på skjermen. Ved å trykke på mellomromstasten kan du bytte mellom å ta hele skjermen eller det gjeldende vinduet. I tillegg er det hurtigtaster for å slå på/av markørvisningen og for å fange et område av samme størrelse som forrige skjermbilde. Den siste funksjonen er veldig praktisk hvis du trenger å ta dusinvis av samme type skjermbilder, siden det sparer tid på å velge ønsket område.

Det resulterende skjermbildet settes umiddelbart inn i dokumentasjonselementet som ble uthevet. Det som er interessant: I navigasjonslinjen er elementer som allerede er lagt til skjermbilder visuelt merket for. Takket være dette kan du umiddelbart finne ut hvilke seksjoner som fortsatt trenger arbeid.

Formatet som skjermbildet skal lagres i, bestemmes i applikasjonsinnstillingene. Programmet kan automatisk generere ALT-tagger for bilder, skalere dem når de settes inn i et dokument til ønsket størrelse (den originale kopien lagres også), legge til en ramme og runde kantene.

Clarify har grunnleggende verktøy for å jobbe med bilder og tekst. Dermed kan bilder roteres, beskjæres, og tekst eller kommentarer kan legges til dem, piler, rektangler og andre grafiske objekter som kan være nyttige for visuelt å fremheve områder i et skjermbilde.

Når du jobber med tekst kan du bruke nummererte og punktlister, innsetting av kode, hyperkoblinger, innrykk. For noen språk fungerer grammatikkkontroll mens du skriver, og det er et søk og erstatning av data i dokumentet.

Du kan samarbeide om Clarify-prosjekter med andre brukere. For å gjøre dette, må du opprette en konto på Clarify-it.com. I tillegg støtter programmet Dropbox og Evernote-tjenester, og gjør det mulig å eksportere prosjekter til PDF-, Word-, HTML- og WordPress-sider. Hvis du ønsker det, kan du også ganske enkelt kopiere hele teksten i dokumentet (eller tekst med bilder) til utklippstavlen.

Når du eksporterer, kan du velge et designtema, legge til topptekster og bunntekster og administrere ulike visningsparametere (avhengig av formatet). For eksempel er tre designtemaer tilgjengelige for eksport til Word, og det ferdige dokumentet presenteres som en perfekt formatert fil, med stiler, overskrifter, lister og hyperkoblinger. Dette er en fornøyelse å jobbe med, spesielt hvis du husker hvor mye tid du trenger å bruke manuelt på å gjøre denne formateringen i Word.

Også interessant er funksjonen til å eksportere alle skjermbilder til en mappe. Når du gjør dette, lagrer Clarify alle bildene som brukes i dokumentet i en gitt mappe og gir hver fil et navn som samsvarer med tittelen på delen den er knyttet til.

⇡ Dr.Forklar 5.3 - halvautomatiske veiledninger med ferdige merknader

• Utvikler: Indigo Byte Systems.
• Distribusjon: shareware, fra 7500 rubler.
• Russisk grensesnitt: ja.

Dr.Explain har ikke et så moderne grensesnitt som Clarify, men dette programmet har sitt eget unike egenskaper. Det viktigste er kanskje automatiseringen av prosessen med å lage teknisk dokumentasjon. Bare spesifiser programvinduet eller tjenestenettsiden du vil beskrive, og Dr.Explain vil uavhengig lage et skjermbilde, analysere alle grensesnittelementer, legge til bildetekster og til og med merke dem der det er mulig.

Hvis det er en meny i grensesnittet til den fangede applikasjonen, vil Dr.Explain definitivt utvide den, ta et øyeblikksbilde av alle undermenynivåer og legge til bildetekster for hvert element. Dessuten vil alle skjermbilder bli plassert i Dr.Explain-prosjektet mens strukturen til dokumentet opprettholdes (det vil si at hovedvinduet vil være i seksjon 1, den utvidede menyen vil være 1.1, og undermenyelementene vil være 1.1. 1, 1.1.2 og så videre). Dermed er alt kjedelig og monotont arbeid utført i automatisk modus, og brukeren trenger bare å legge til en beskrivelse av alle grensesnittelementer. Det er tydelig at strukturen til dokumentet kan endres ved å flytte elementer, legge til nye og slette unødvendige.

Selv før du tar skjermbilder, kan du konfigurere mange innstillinger relatert til bilder. For eksempel er det mulig å angi plasseringen av bildetekster, stilen på merknader, og bestemme alternativet for å generere filnavn (i samsvar med seksjonsoverskrifter eller deres nummer).

Har du tidligere jobbet med dokumentasjon i en annen applikasjon, kan du enkelt importere prosjektet og programmet. Dr.Explain støtter import av CHM, Word, HTML, HLP, RTF, TXT, XML-dokumenter.

Samarbeid om dokumentasjon er organisert gjennom Tiwri.com-tjenesten, laget spesielt for datautveksling mellom Dr.Explain-brukere. Fra programvinduet kan du laste opp det gjeldende prosjektet til serveren, sende endringer, tilbakestille redigeringer og spore historikk.

CHM, Word, HTML og PDF-formater er tilgjengelige for eksport av ferdig dokumentasjon. Dessuten, selv før du eksporterer, kan du se hvordan manualen vil se ut i et av disse formatene. Før du eksporterer, må du huske å gå til prosjektinnstillingene og angi Ekstra alternativer. Når du for eksempel lagrer et dokument som PDF, kan du spesifisere nøkkelord, forfatter, tittel, emne og format, tilpasse overskrifter og sidetall og lage bokmerker for seksjoner. Ved eksport til HTML er det mulig å tilpasse nettstedskartet, legge til kommentarer for Facebook-brukere og Disqus, aktiver visning av et panel med knapper for sosiale nettverk, spesifiser detaljene til FTP-serveren som prosjektet skal lastes opp til.

Til slutt er det verdt å ta hensyn til det faktum at Dr.Explain er et produkt fra innenlandske utviklere, så det er ganske forventet at du kan finne full støtte for det russiske språket i det.

⇡ Manula - overføring av manualer online

• Utvikler: Bitz & Pixelz.
• Operativsystem: alle.
• Distribusjon: ved abonnement (fra $10 per måned).
• Russisk grensesnitt: nei.

Tidlig i 2009 bestemte Alwin Hoogerdijk, skaperen av Collectorz.com-familien av applikasjoner for samlingsadministrasjon, å lage online hjelp for programmene sine. Han var lei av at han ofte måtte utsette utgivelsen av nye versjoner av programmer på grunn av at endringer i brukerdokumentasjonen ennå ikke var klare, eller omvendt gjøre nye utgivelser tilgjengelige for nedlasting med utdaterte hjelpefiler, og slipp deretter nye bygg der de oppdaterte kun manualer.

For å gjøre prosessen med å legge til dokumentasjon mer praktisk for utviklere, og få tilgang til den raskere for brukere, ønsket Alvin å flytte alt på nettet. Han begynte å søke etter et spesialisert innholdsstyringssystem for å lage teknisk dokumentasjon. Og da det viste seg at ingenting slikt eksisterte, skapte utvikleren eget system for din familie av applikasjoner. Det ble senere utviklet til et mer allsidig kommersielt produkt, Manula.com.

Manula.com lar deg lage og oppdatere manualer i nettleseren din, uten behov for skrivebordsapplikasjoner. Den største fordelen med en online manual er umiddelbar oppdatering. Så snart utviklerne har gjort endringer i den, er de oppdaterte hjelpefilene allerede tilgjengelige for brukere - det er ikke nødvendig å eksportere noe hvor som helst, laste opp HTML-filer til serveren, og så videre. Samtidig ser manualer like bra ut på alle enheter – på store skjermer, nettbrett eller smarttelefoner. Tjenesten tilpasser seg automatisk skjermstørrelsen.

Og hvis brukeren ønsker å få en kopi av manualen for offline visning, er dette ikke vanskelig i det hele tatt. Manula tilbyr praktisk nedlasting av manualer laget på plattformen i PDF-format.

Manula har også innebygde verktøy for å spore endringer og motta tilbakemeldinger fra brukere. De blir bedt om å vurdere spesifikke temaer i referansedokumentasjonen. For utviklere er det visuell statistikk over rangeringer og antall besøk ulike seksjoner Håndbok. Takket være dette kan du alltid forstå hvor manualen må forbedres, gjøres mer detaljert eller kobles til andre seksjoner.

Håndbøker laget med Manula har et integrert søkesystem - seksjonsoverskrifter, dokumentasjonsinnhold og nøkkelord spesifisert av utvikleren tas i betraktning. Tjenesten lagrer historikk søk og viser det til utviklerne populære spørsmål, noe som gjør det enkelt å gjøre endringer i titler og søkeord.

En av de interessante funksjonene til Manula er funksjonen for emnedeling. Hvis et selskap har flere lignende produkter, kan individuelle hjelpefragmenter gjøres felles for dem. Hovedforskjellen fra enkel kopiering ferdige dokumentasjonsfragmenter er at når du bruker funksjonen for emnedeling, trenger du bare å gjøre endringer på ett sted. I dette tilfellet vil dokumentasjonen bli oppdatert automatisk i alle applikasjoner. Variabler (for eksempel (APPNAME)), som er konfigurert separat for hver brukerhåndbok, bidrar til å automatisere prosessen ytterligere.

Vanlige hjelpebiter kan også brukes til å lage separat dokumentasjon for ulike versjoner av en applikasjon. For å forhindre at brukere kaster bort tid på å søke etter funksjoner de ikke har, kan du lage separate manualer for hver versjon. I dette tilfellet vil hoveddelen av hjelpen administreres ved hjelp av funksjonen for emnedeling.

Det er ikke noe innebygd verktøy for å ta skjermbilder i Manula - du må laste ned ferdige bilder til bildebiblioteket (det er felles for alle prosjekter) og lim det deretter inn på de nødvendige stedene i dokumentasjonen. Å legge til tekst gjøres også i nettredaktøren, og her kunne tjenesteutviklerne finne på noe interessant. Sammen med å bruke visuell redaktør Det anbefales å jobbe med tekstilkoder for å fremskynde formateringsprosessen. Disse kodene gjør det mulig å formatere tekst uten å måtte ha tilgang til redigeringsknappene. For eksempel, hvis tekst må utheves, må den bare omsluttes av to stjerner (*som dette*), og for å lage en overskrift på første nivå, skriver du bare h1- på begynnelsen av linjen.

⇡ StepShot - vil ta bilder, ordne dem i rekkefølge og signere dem

• Utvikler: StepShot.
• Operativsystem: Windows.
• Distribusjon: ved abonnement ($29 per måned). Det er en fullt funksjonell prøveversjon i 14 dager, som deretter blir begrenset.
• Russisk grensesnitt: nei.

Nesten hver brukerveiledning inneholder nødvendigvis instruksjoner som forklarer hvilke skritt som må tas for å oppnå et gitt resultat. Det er en glede å lese slike guider, der hvert trinn er ledsaget av et skjermbilde og forklaring, men opprettelsen av dem tar ofte mange timer. Noen tekniske skribenter skriver teksten først og tar deretter alle skjermbildene og limer dem inn på de riktige stedene, andre foretrekker å ta skjermbilder ett om gangen, lime dem inn i manualen og umiddelbart legge til en beskrivelse. Det viser seg uansett å være ganske arbeidskrevende.

StepShot er et utmerket program som bidrar betydelig til å fremskynde opprettelsen av trinnvise instruksjoner. Det hjelper deg raskt å ta alle skjermbildene, uten å bli distrahert av å lagre og lime inn, og plasserer dem i i riktig rekkefølge, hjelper deg å legge til beskrivelser og merknader, og deretter publisere i et av de populære formatene.

Arbeid i StepShot er bygget i form av en veiviser. Trenger å lage nytt prosjekt, og start deretter fangstprosessen og begynn å utføre de handlingene som er underlagt dokumentasjon. Hver gang du klikker med musen, vil programmet lage et skjermbilde og lagre det. Samtidig er StepShot-panelet konstant på skjermen, som du kan stoppe opptaksprosessen med og endre modusen for å ta skjermbilder (hele skjermen, aktivt vindu, valgt rektangulært område).

Dette panelet er selvfølgelig ikke synlig i skjermbildene. Avhengig av innstillingene, kan fangsten bare skje når du klikker mens du holder nede CTRL (eller en annen praktisk tast) eller omvendt i alle tilfeller bortsett fra når brukeren holder nede den angitte tasten. I programinnstillingene kan du også stille inn forsinkelsen mellom klikket og opprettelsen av skjermbildet.

Når er fullført, vil alle resulterende bilder åpnes i StepShot-vinduet. Til venstre er et navigasjonspanel med miniatyrbilder av bilder, til høyre er et skjermbilde det jobbes med, samt et område for å legge til en beskrivelse. Skjermbildene er allerede ordnet i den rekkefølgen de ble tatt, men om nødvendig kan de omorganiseres ved å dra musen. I tillegg kan hvert trinn (skjermbilde med beskrivelse) kopieres eller slettes, eller du kan også legge til et tomt trinn foran det, som du for eksempel kan importere et bilde fra disk.

Hvis instruksjonen er lang, er det fornuftig å dele den opp i seksjoner ved å legge til separatorer på de riktige stedene. For hver seksjon er det mulig å sette et navn. Basert på avsnittene vil det automatisk bli generert en innholdsfortegnelse, som vil bli plassert i begynnelsen av manualen.

Vanligvis, når du lager opplæringsprogrammer, brukes mye tid på å markere området der markøren er plassert i skjermbildet (vanligvis stedet der du må klikke). StepShot gjør det mulig å automatisere denne rutinehandlingen også. Grensesnittelementet som klikkes på kan automatisk fremheves med et rødt rektangel eller en gul sirkel. I tillegg kan programmet automatisk jevne ut kantene på skjermbilder.

På stadiet med redigering av de mottatte skjermbildene - allerede inne manuell innstilling- du kan legge til piler, infomeldinger eller andre grafiske elementer og fremhev visse områder av bildet med farger. Og hvis du trenger å trekke leserens oppmerksomhet til flere områder i ett skjermbilde, kan du bruke sekvensverktøyet. Dette lager linjer med tall på slutten. Bare plasser dem på de riktige stedene i bildet og legg til en beskrivelse.

Å legge til beskrivelser er også så automatisert som mulig. Siden de samme setningene oftest brukes når du skriver teknisk dokumentasjon, gir programmet skjermbilder med beskrivelser som "Klikk på "Skype"-knappen." For å gjøre dette, fanger den opp navnene på grensesnittelementer, gjenkjenner dem og legger dem deretter til bildeteksten under bildet. Dette fungerer imidlertid bare for engelsk og et par andre europeiske språk, og kompilatorene av russiskspråklig dokumentasjon må legge til alle beskrivelsene manuelt.

Formateringsalternativer i StepShop er grunnleggende - du kan endre skriftstørrelsen for skjermdumptitler og beskrivelser, markere tekst i fet, kursiv eller understreket, kontrollere innrykk og sette inn hyperkoblinger. Ikke glem at du kan legge til en beskrivelse og forfatter for prosjektet ditt før du eksporterer.

Når du er ferdig med å lage guiden, kan du eksportere den til ett av flere støttede formater: Word-dokument, PDF, HTML, DITA eller XML. Det finnes imidlertid flere forskjellige maler tilgjengelig for Word.

Det er også direkte publisering til Wordpress og Confluence, og alle bilder som brukes i prosjektet foreslås lagret i én mappe. Dessverre kan du kun kontrollere kvaliteten på bildene, men du kan ikke endre navnene. Skjermbilder lagres med navn som image0001.jpg, image0002.jpg, noe som ikke alltid er praktisk (det ville vært fint om det var mulig å navngi bilder basert på titler i prosjektet).

Til tross for at StepShot distribueres på betalt basis, kan du jobbe med programmet gratis hvis du er villig til å tåle et vannmerke på de resulterende bildene. I tillegg, gratis versjon lar deg opprette opptil fem eksporterte prosjekter per måned.

⇡ iorad - analogStepShot, men i nettleseren

• Utvikler: iorad inc.
• Operativsystem: alle.
• Distribusjon: ved abonnement ($90 per måned). Det er en begrenset gratisversjon.
• Russisk grensesnitt: nei.

For å komme i gang med iorad må du installere en utvidelse for Google Chrome og åpne en nettside, handlingene skal dokumenteres på. Etter dette må forfatteren klikke på utvidelsesknappen. Nettjenesten iorad bruker samme tilnærming som StepShot (forfatteren av instruksjonene utfører alle trinnene, tjenesten lagrer dem, deler dem ned i trinn, som deretter kan redigeres og publiseres som en leksjon). Imidlertid fungerer iorad som en nettleserutvidelse, og all behandling, redigering og publisering av trinnvise instruksjoner gjøres på serveren. På den ene siden er dette praktisk, siden tjenesten er tilgjengelig på enhver plattform, men det er en irriterende begrensning - ved å bruke iorad kan du bare registrere handlinger utført i nettleseren. Det vil si at tjenesten kun egner seg for å lage manualer for webapplikasjoner, og er ikke egnet for skrivebordsprogrammer.

Når den er trykket, vil iorad gi tre sekunder på seg til å forberede seg før opptaket begynner. Tjenesten gjenkjenner og lagrer alle handlinger - museklikk, dobbeltklikk, vindusrulling, skriving og så videre. Når registreringen av instruksjonene er fullført, trenger du bare å klikke på utvidelsesknappen på Chrome-panelet igjen. Prosessen kan også settes på pause en stund og deretter gjenopptas.

Når opptaket er fullført, vil iorad gjenopprette alle brukerhandlinger og dele opp instruksjonene i trinn. Alle grensesnittelementer som ble aktivert vil bli uthevet (for eksempel en knapp som må klikkes). I tillegg legger iorad automatisk til enkelt tekstinstruksjoner for hvert trinn.

Hver leksjon begynner med setningen "Det første trinnet er å åpne [navn på nettsiden]" og slutter med uttrykket "Det er det". Du er ferdig." Til tross for at beskrivelser automatisk kun kompileres på engelsk, er det i de ferdige instruksjonene mulig å se dem på andre språk på grunn av integrasjon med Google Oversetter. Hvis du ikke legger til lange beskrivelser, men begrenser deg til enkle fraser, fungerer en slik oversettelse tålelig.

Men hvis du bruker litt tid, kan du umiddelbart legge til en beskrivelse på morsmålet ditt. Det er imidlertid verdt å huske at lengden på beskrivelsen er begrenset til 250 tegn. Den kan bruke forskjellige skriftstiler, så vel som hyperkoblinger. I tillegg kan du legge til opptil ett minutt med lydinstruksjoner for hvert trinn. Det kan tas opp direkte i nettapplikasjonsgrensesnittet eller lastes ned fra filer tilgjengelig på datamaskinen din.

Når det gjelder verktøy for å redigere skjermbilder, har skaperne av iorad fortsatt litt arbeid å gjøre. Alt brukeren kan gjøre er å gjøre en del av bildet uskarpt og endre størrelsen og plasseringen av utvalgsrammen.

Ferdige instruksjoner kan lagres som filer Word Doc, PowerPoint og PDF, og innebygd på nettsteder eller vist i en nettleser på hvilken som helst plattform, skrivebord eller mobil. Ved å bruke de to siste alternativene kan du sette pris på hovedfordelen med iorad - interaktivitet. Instruksjonene mottatt ved hjelp av tjenesten lanseres i en spesiell spiller. Brukeren kan velge ett av alternativene for å jobbe med det: vise eller uavhengig gjenta alle trinnene.

I det første tilfellet vises alle skjermbilder og beskrivelser for dem på én side, og du kan ganske enkelt lese hva du skal gjøre. I det andre tilfellet blir brukeren bedt om å gjenta alle handlingene til forfatteren for å oppnå ønsket resultat. Det vil si at han leser beskrivelsen av skjermbildet, utfører handlingen, og først etter det går han videre til neste trinn. Perfekt løsning for å sikre at brukeren faktisk forstår hva de må gjøre.

⇡ Konklusjon

Spesialiserte programmer for å lage manualer kan øke hastigheten på opprettelsen av teknisk dokumentasjon betydelig. Hvor klar, detaljert og strukturert hjelpefilen vil være, avhenger imidlertid helt av kompilatorene.

Når du arbeider med dokumentasjon, er det alltid verdt å huske "Goldilocks-prinsippet": brukeren skal ikke gis for mye informasjon, ikke for lite, men nøyaktig så mye som er nødvendig for å fullføre oppgaven. God dokumentasjon skal fungere som en navigator: når brukeren har vist hvor han er (hvilket problem han har støtt på), bør han umiddelbart bruke hjelpefilen for å finne riktig vei (løsning på problemet). Og selvfølgelig, ikke glem om hyperkoblinger, som du må gi fri bevegelse bruker i henhold til manualen. Hvis i hendene hans detaljert PDF 100 sider lang, hvor det ikke er referanser, kan kvaliteten på slik dokumentasjon vanskelig vurderes av andre enn kompilatoren.

Imidlertid moderne verktøy for å lage referanseguider er så mangfoldige og multifunksjonelle at det ikke er vanskelig i det hele tatt å lage detaljert, forståelig og godt utformet dokumentasjon med deres hjelp.

@ Zhuravlev Denis

Mange IT-selskaper som utvikler og vedlikeholder programvare og automatiserte systemer står overfor oppgaven med å lage brukerdokumentasjon for produktene sine i henhold til GOST-kravene.

Som regel oppstår behovet for dokumentasjon i samsvar med GOST i samarbeid med offentlige organisasjoner, store industrier og selskaper, i tilpasset utvikling av programvare for anbud og offentlige ordre, eller hvis det er nødvendig å legge til et programvareprodukt til " Enkelt register Russiske programmer for elektronisk datamaskiner og databaser (register over innenlandsk programvare)".

Det er to serier (sett) med standarder som regulerer settet opprettet dokumenter og regler for deres design ved utvikling av automatiserte systemer, komplekser og programvare:

• GOST 34 - Automatiserte systemer
• GOST 19 - Unified System of Program Documentation (USPD)

På den ene siden konkurrerer disse to standardene med hverandre, foreslår jeg ulike alternativer fullstendigheten av prosjektdokumentasjonen. På den annen side fokuserer de på ulike aspekter og utfyller derfor hverandre godt.
GOST 34 bestemmer hovedsakelig fullstendigheten, typene, strukturen og innholdet i dokumenter som er opprettet.
GOST 19 bestemmer i stor grad reglene for å utarbeide dokumenter.
Derfor, i praksis, brukes begge disse GOST-ene ofte samtidig.

Hvis vi snakker spesifikt om dokumentasjon for sluttbrukeren av systemet, er vi fra listen over dokumenter beskrevet i GOST 34 interessert i "Brukerhåndboken". I GOST 19 kalles et dokument med lignende betydning "Operator's Manual", men for programvare er det det første alternativet som oftest brukes.

En brukerhåndbok følger med ethvert produkt, program eller system. Den skal gi brukeren informasjon om egenskapene til produktet, dets funksjonalitet, hvordan man bruker det og hvordan man arbeider med det.

For en nybegynner teknisk skribent eller en enkel spesialist som uventet får i oppgave å utarbeide en GOST-brukerhåndbok, er denne oppgaven et alvorlig problem.

Ikke bare er det nødvendig å studere et stort antall reguleringsdokumenter, fylt med kryssreferanser og skrevet på et komplekst, altfor geistlig, nesten juridisk språk, men det er også nødvendig å velge fra dem kravene som spesifikt er knyttet til typen som opprettes dokument. Deretter, gjennom hele arbeidet, må du hele tiden overvåke overholdelse av disse kravene i arbeidsdokumentet, og kontinuerlig sjekke standardene.

Vanligvis forverres problemet av mangel på tid, siden skriving av brukerdokumentasjon, dessverre, ofte er vanlig helt på slutten av prosjektet, før selve deadline - datoen for levering eller lansering av systemet.

For en erfaren teknisk skribent kan dokumentasjon i henhold til GOST ikke forårsake alvorlige problemer. Men selv for ham kan det ta betydelig tid å utarbeide maler for nye dokumenter, bringe eksisterende dokumentasjon til kravene i standarder, eller sjekke det endelige dokumentet for samsvar med disse kravene.

Dr.Explain forenkler opprettelsen av en brukermanual i henhold til GOST

Fra og med versjon 5.5.1100 tilbyr programmet for å lage brukerdokumentasjon Dr.Explain funksjonen til automatisert GOST-støtte i prosjekter. Denne funksjonen er designet for å gjøre livet mye enklere for brukere som står overfor oppgaven med å lage en brukerhåndbok i samsvar med kravene i myndighetenes standarder.

Spesielt kontrollerer og automatiserer programmet Dr.Explain støtte for følgende standardkrav:

• Tilgjengelighet av obligatoriske deler av dokumentet "Brukerveiledning" [GOST 34 RD 50-34.698-90]. Alle seksjoner er utstyrt med forklaringer av innholdet.
• Design av tittelsider, merknader og innhold [GOST 19.105-78, 19.104-78].
• Parametre for utskrevne sider i et dokument og plasseringen av hovedelementene på dem [GOST 19.106-78].
• Struktur og design av topptekster og bunntekster [GOST 19.106-78].
• Design av tekstdelen av dokumentet: skriftstiler, avsnittsinnrykk, linjeavstand [GOST 19.106-78].
• Dannelse og utforming av overskrifter, seksjoner, oppregninger (lister) [GOST 19.106-78].

Administrering av GOST-støttefunksjonen for et prosjekt er tilgjengelig i Prosjektinnstillinger i delen Er vanlig.

Når GOST-støttemodus er aktivert for et prosjekt, blir de tilsvarende brukerinnstillingene for trykte RTF\DOC- og PDF-formater automatisk overstyrt av programmet, noe som garanterer full overensstemmelse med parametrene til utdatadokumentene med kravene til standardene.

Til helgen HTML-formater og CHM, vil brukerinnstillingene bli brukt uavhengig av om GOST-støttemodusen er aktiv. Dette fjerner begrensningen på gratis styling av disse formatene og tillater for eksempel å designe en online hjelp helt i en bedrifts- eller tematisk stil.

Viktig:

Viktig: GOST-støttefunksjonen er kun tilgjengelig i Dr.Explain i den russiske versjonen av grensesnittet. Programgrensesnittspråket velges i menyen Innstillinger\Velge programspråk (Alternativer\Programspråk).

Oppretting av en ny brukerhåndbok i henhold til GOST

For å lage en ny brukerveiledning i henhold til kravene til GOST 34 i Dr.Explain-programmet, kan du bruke menykommandoer Fil\Opprett lokalt prosjekt - Brukerveiledning i henhold til GOST 34 eller Fil\Ny generelt prosjekt på tiwri.com - Brukerhåndbok i henhold til GOST 34

eller lignende knapper på startskjermen applikasjoner.

Programmet vil opprette et nytt prosjekt, som allerede inneholder en tittelsidemal, merknad, innholdsfortegnelse og obligatoriske seksjoner, formatert i samsvar med GOST.

Teksten til hver del vil gi et kort instruksjonstips om hva som må inkluderes denne seksjonen. Brukeren trenger kun å fylle seksjonene med relevant innhold.

Designinnstillinger for trykte formater RTF/DOC og PDF vil bli satt i samsvar med kravene i GOST 19.

Bringe eksisterende brukerdokumentasjon i samsvar med GOST-kravene

Dr.Explain-programmet lar deg også ta med eksisterende brukerdokumentasjon i samsvar med GOST-kravene.

Viktig: Før du aktiverer GOST-støttemodus for prosjekter som allerede eksisterer i Dr.Explain-formatet, må du lage en sikkerhetskopi av prosjektets gui-fil.

Hvis kildedokumentasjonen ennå ikke er vedlikeholdt i Dr.Explain, men er lagret i andre formater, er det første trinnet å importere eksisterende dokumenter inn i programmet. Dr.Explain støtter import av dokumenter fra en rekke populære formater. Importkommandoer er tilgjengelige både i programmets startvindu og i menyen Fil.

Deretter må du aktivere GOST-støttemodus i prosjektegenskapene på den måten som er beskrevet tidligere. Programmet vil sjekke dokumentstrukturen for tilstedeværelsen av nødvendige seksjoner og, hvis de mangler, vil opprette dem. De gjenværende eksisterende seksjonene, hvis tilstedeværelse ikke er regulert av GOST-er, vil bli flyttet til seksjonen "skjult fra eksport" Gammelt skilletre”.

Brukeren må dra og slippe innholdet i disse seksjonene eller hele seksjonene inn i hovedprosjekttreet og redigere dem etter behov.

Som i det første tilfellet vil designinnstillingene for trykte formater RTF/DOC og PDF settes i samsvar med kravene i GOST 19.

En brukermanual er en oppslagsbok på papir eller digitale medier (i PDF- eller XPS-format) som gir instruksjoner for å betjene noe eller beskriver riktig prosedyre for å utføre en prosess. Selv om når en person hører uttrykket "brukerhåndbok", tenker de vanligvis på en manual for bruk av et spesifikt program, har datamaskiner og husholdningsapparater (TVer, stereoanlegg, telefoner, MP3-spillere, hageutstyr, etc.) bruksanvisninger. . En god bruksanvisning forklarer de grunnleggende funksjonene til enheten eller programmet og forklarer hvordan du bruker den riktig, og informasjonen er vanligvis godt organisert. Denne artikkelen vil fortelle deg hva som er viktig å huske når du lager og designer en brukermanual.

Trinn

Del 1

Opprette dokumentasjon

Bestem hvem leseren din er. For å lage en god brukerhåndbok, må du forstå hva slags person som vil kjøpe enheten du lager instruksjoner for. Du kan skrive ned tankene dine, eller du kan bare forestille deg denne personen. Dette er nyttig å gjøre hvis du er en del av et dokumentasjonsteam og hvis du er involvert i utviklingen av et produkt fra start til slutt. Vurder følgende:

• Hvor vil en person bruke bruksanvisningen: hjemme, på jobb, i bilen, på Internett? Dette vil avgjøre ikke bare innholdet, men også stilen til dokumentasjonen.
• Hvordan vil en person bruke instruksjonene? Hvis en person bare trenger å se i bruksanvisningen av og til, bør instruksjonene presenteres i en kortfattet form. Hvis håndboken vil bli brukt ofte, spesielt helt i begynnelsen, bør du inkludere en hel del om hvordan du kommer i gang med å bruke enheten eller programvaren og detaljere alle de viktigste funksjonene.
• Hvor mye erfaring bør en person ha? Hvis produktet ditt er relativt nytt eller vesentlig forskjellig fra lignende produkter, må du inkludere informasjon om hvordan dette produktet skiller seg fra lignende produkter og gi brukeren detaljerte instruksjoner. Hvis produktet er knyttet til hyppige problemer(for eksempel med stort beløp programmer), beskriver hva du skal gjøre når et problem oppstår.

1. Skriv på en slik måte at leseren forstår deg. Med mindre produktet ditt krever at brukeren har spesifikk kunnskap, er det bedre å unngå tekniske termer og beskrive alt på et enkelt og forståelig språk. Strukturen i teksten skal samsvare med rekkefølgen av spørsmål som brukeren måtte ha. Det er mer riktig å gruppere funksjonene til enheten avhengig av oppgavene den utfører, og forlate ideen om å kombinere de mest populære funksjonene i en gruppe.

   • Noen ganger er det umulig å fullstendig eliminere tekniske termer (for eksempel hvis du skriver instruksjoner for et program for å lage grafer og diagrammer, som i tillegg til standardverktøy, også bruker grafiske verktøy Fibonacci). I dette tilfellet er det nyttig å definere begrepet og gi en kort beskrivelse (dvs. hva er Fibonacci-diagrammer og hvordan brukes de i økonomisk resultatanalyse).

2. Del 2

   Komponenter i brukerhåndboken

   1. Vurder omslaget og utformingen av de første sidene av seksjonene. Du må lage et omslag hvis instruksjonene er på flere sider. Det vil også være nødvendig å lage sider med navn på seksjoner for instruksjoner der den totale informasjonsmengden tar opp mer enn 4 sider.

      • Hvis brukerhåndboken er beskyttet av opphavsrett, må merknaden vises på omslaget og på seksjonssidene.
      • Hvis brukerhåndboken gir spesifikke betingelser for bruk av produktet og instruksjoner for det, plasser denne informasjonen på innsiden av omslaget.

   2. Plasser lenker til tilleggsdokumentasjon i introduksjonen. Hvis manualen består av flere brosjyrer, skriv opp alle brosjyrenumre i begynnelsen. I tillegg bør du også inkludere en "Hvordan bruke denne bruksanvisningen"-delen her hvis du bestemmer deg for at en slik del er nødvendig.

      Hvis antall sider overstiger 10, trenger du en innholdsfortegnelse.

   3. Bruksanvisningen skal være basert på instruksjoner og informasjon om komponentene i produktet. Som regel er instruksjoner delt inn i blokker, og i hver blokk kan du angi i hvilke seksjoner brukeren skal se etter denne eller den informasjonen. Dette vil gjøre det enklere og raskere for brukeren å finne informasjonen han trenger.

      • Prosesser skal beskrives klart og konsekvent. Start med en generell beskrivelse av oppgaven, forklar deretter hva brukeren må gjøre og hva resultatet blir. Alle trinn skal nummereres, og setninger må begynne med verb.
      • Hjelpemateriell bør inneholde en liste over funksjoner, feilsøkingsteknikker og vanlige spørsmål. På slutten av bruksanvisningen kan du plassere kort ordbok termer og en alfabetisk indeks, selv om hovedbegrepene ofte er plassert i begynnelsen. En alfabetisk indeks anbefales for instruksjoner som er lengre enn 20 sider.

   4. Bruk bilder og diagrammer. Tegninger og skjermbilder kan beskrive visse prosesser bedre enn tekst, spesielt når det gjelder komplekse prosesser hvor det er nødvendig å ha visuell bekreftelse på at en person gjør alt riktig. Grafiske bilder kan lages i spesielle programmer: i to- og tredimensjonale tegnesystemer, i grafiske redaktører, i fotobehandlingsapplikasjoner, etc. Hvis du trenger å ta skjermbilder, kan de fås ved hjelp av standard dataverktøy og grafikk program med muligheten til å lagre skjermbilder.

      • Etter at du har mottatt grafisk bilde, lagre den i et komprimert format. Du må kanskje også redusere størrelsen på tegningen for å passe på siden, men størrelsen bør ikke være for liten, ellers vil ikke brukeren kunne se hvordan og hva den skal gjøre. Om nødvendig kan du dele bildet i flere deler og beskrive hver av dem.
      • Hvis du bruker flere bilder, må de ha samme størrelse, sideforhold og oppløsning. Slike bilder vil være mer forståelige og gledelige for leseren. Når du tar skjermbilder, sørg for at du bruker standarden fargevalg(for tilfeller der manualen er trykt i farger).
      • Selv om grafisk redaktør(for eksempel Photoshop og Paint Shop Pro) er praktiske for å lage skjermbilder; det er bedre å bruke spesielle programmer (for eksempel SnagIt), siden de lar deg raskt og enkelt redigere, lagre og signere alle bilder.

      Del 3

      Utarbeidelse av bruksanvisning

      1. Velg en lesbar font. Selv om datamaskiner støtter forskjellige fonter, brukermanualen skal være lett å lese, så gi preferanse til de enkleste. Det er best å velge flere fonter som ser bra ut sammen. Det finnes to typer fonter: serif og sans serif.

         • Serif-fonter har små streker langs kantene på linjene. Disse skriftene inkluderer Times New Roman, Baskerville og Book Antiqua. Slike fonter er egnet for store tekstvolumer som er skrevet ut i størrelse 10 eller 12 og danner grunnlaget for brukerhåndboken.
         • Sans serif-fonter har enkle linjer uten utsmykning. Dette er fonter som Arial, Calibri og Century Gothic. Sans serif-fonter ser bedre ut i tekster skrevet ut i skriftstørrelse 8 eller 10 i PDF-håndbøker eller nettdokumenter. Jo større skrift, desto vanskeligere er det å lese sans serif. Disse skriftene kan imidlertid også brukes til stor tekst - for eksempel til å skrive overskrifter. Sans serif-fonter er egnet for å skrive tall i tabeller og kolonner.
         • Bør velge enkle fonter som Arial eller Times New Roman, selv om en mer kompleks font ville være egnet for sitater. Hvis du skriver en brukermanual for et fantasyspill, kan det være lurt å fremheve kapitteltitlene med en blomstrende skrift. Sitater kan også være kursiv.
         • Etter at du har valgt skriftene dine, oppretter du en testside for å sikre at skriftene fungerer godt sammen på papir. Vis denne siden til personen som godkjenner oppsettene før du sender brukermanualen til utskrift.

      2. Tenk over utformingen av informasjonsblokker. På dette tidspunktet må du bestemme i hvilken rekkefølge du vil plassere informasjonen.

         • Vanligvis er tittelen på brukerhåndboken og kapitteltitlene plassert øverst eller nederst på siden, sammen med sidetall. Tallene kan være plassert på utsiden (for toppen og bunnen av siden) eller i midten (for bunnen). Den første siden i hver seksjon kan være forskjellig fra de andre, så det kan være lurt å plassere sidetallet i midten nederst og alle andre sidetall på utsiden.
         • Individuelle tekstfragmenter kan utheves i farger ved å plassere dem i spesielle blokker. Det er viktig å velge en nyanse som ikke tetter teksten.
         • La nok store innrykk fra alle kanter. På innbindingssiden skal fordypningen være bredere.

      3. Vurder typen binding. Hvis brukermanualen din er på mer enn 4 sider, trenger du en perm. Dokumenter for intern bruk stiftes vanligvis i hjørnet, men hvis du legger håndboken i produktesken, må du ta mer ansvar for dette problemet. Det er tre typer binding:

         • Stiftefeste. Denne typen passer for brosjyrer som måler 21 x 27,5 cm, 21 x 35 cm eller 11 x 27,5 x 42,5 cm De fleste rimelige bruksanvisninger som er på 48 sider eller mindre er innbundet på denne måten.
         • Binding med ryggstikk. Slik henger de fleste sammen vanlige instruksjoner manualer, ikke medregnet bilmanualer, selv om noen lange manualer også er bundet inn på denne måten. (Paint Shop Pro ble opprinnelig levert med denne brukerhåndboken.)
         • Binding med trådspiral. Håndbøker som brukes i tøffere miljøer, for eksempel utendørs, hvor stifter lett kan gå i stykker eller gå fra hverandre, er bundet inn på denne måten. Noen bruksanvisninger med denne innbindingen inneholder også laminerte sider som ikke blir våte eller skitne til.

      4. Sett opp dokumentet. I flertall tekstredigerere og programmer for publisering av tekst på Internett gir mulighet for layout. Når du skriver inn tekst, vil den automatisk vises i den valgte fonten. (Denne artikkelen ble opprinnelig skrevet med en mal i Microsoft Word.) Disse programmene har også allerede ferdige maler, som du kan endre for å passe dine behov i stedet for å lage en mal fra bunnen av.

         • Tekstbehandlere og programmer for publisering av tekst på Internett har også muligheten til å lage "stiler", lagre fonter og angi størrelser for innholdsfortegnelser, bunntekster og brødtekst. Du kan velge mellom eksisterende stiler ("Heading1", "Normal", "Quote") eller lage din egen stil og gi den ditt eget navn. Det anbefales å navngi stiler med samme system som i programmet. (For eksempel lager Microsoft Word titler som «Overskrift1», «Overskrift2»; det er også underoverskrifter.) Sett opp programmet på forhånd slik at du ikke trenger å gå tilbake til det når du begynner å skrive teksten.
      • Bruk feltkoder eller tekstvariabler når det er mulig. Du kan endre betydningen deres (for eksempel produktnavn, brukerhåndbokens kapitteltittel) og plassere dem på steder i dokumentet ditt der du vanligvis skriver inn ord for hånd. Når du forhåndsviser et dokument eller klargjør det for utskrift, settes den nødvendige teksten inn i variablene. Hvis produktnavnet endres eller hvis du bestemmer deg for å endre tittelen på kapitlet, vil det være lettere for deg å endre teksten ved å erstatte verdien til variabelen.

      Hva du trenger

      • Tekstredigerer eller program for publisering av tekst på Internett
      • Grafikkredigeringsprogram eller skjermbildeprogram

I avsnittet Kilder brukt i utviklingen, angi en liste over vitenskapelige og tekniske publikasjoner, regulatoriske og tekniske dokumenter og annet vitenskapelig og teknisk materiale som det refereres til i kildeteksten.

Det forklarende notatet er satt sammen av fagfolk innen programvareutvikling og for spesialister på samme ferdighetsnivå. Derfor er det hensiktsmessig å bruke spesiell terminologi, henvise til spesiallitteratur osv.

11.3. Brukerhåndboken

Som nevnt ovenfor brukes for tiden ofte et annet driftsdokument, som delvis inkluderer en manual systemprogrammerer, programmerer og operatør. Dette dokumentet kalles brukerveiledningen. Utseendet til et slikt dokument var en konsekvens av den omfattende spredningen personlige datamaskiner, arbeider med hvilke brukere som kombinerer de tre spesifiserte spesialistene.

Utarbeidelse av dokumentasjon for brukere har sine egne kjennetegn på grunn av at brukeren som regel ikke er profesjonell innen programvareutvikling. Boken til S. J. Grimm gir anbefalinger for å skrive slik programdokumentasjon:

ta hensyn til brukernes interesser - håndboken må inneholde alle nødvendige instruksjoner for brukeren;

være tydelig og bruke korte setninger;

unngå teknisk sjargong og høyt spesialisert terminologi; hvis det fortsatt er nødvendig å bruke noen begreper, bør de forklares;

vær presis og rasjonell - lange og forvirrende manualer leses vanligvis ikke av noen, for eksempel er det bedre å gi en tegning av et skjema enn å beskrive det i lengden.

Brukerhåndboken inneholder vanligvis følgende avsnitt:

generell informasjon om programvareproduktet;

installasjonsbeskrivelse;

lanseringsbeskrivelse;

bruksanvisning (eller brukergrensesnittbeskrivelse);

meldinger til brukeren.

Kapittel Generell informasjon Om programmet inneholder vanligvis navnet på programvareproduktet, en kort beskrivelse av dets funksjoner, implementerte metoder og mulige bruksområder.

Installasjonsdelen inneholder vanligvis Detaljert beskrivelse handlinger for å installere programvareproduktet og meldinger som kan mottas.

Lanseringsdelen beskriver som regel trinnene for å starte programvareproduktet og meldingene som kan mottas.

Kapittel Bruksanvisningen inneholder vanligvis en beskrivelse av driftsmoduser, input/output formater og mulige innstillinger.

Kapittel Meldinger til brukeren må inneholde en liste mulige meldinger, en beskrivelse av innholdet deres og handlinger som må iverksettes som svar på disse meldingene.

11.4. Systemprogrammeringsveiledning

I henhold til GOST 19.503-79 må systemprogrammererens manual inneholde all nødvendig informasjon for å installere programvaren, konfigurere den og teste funksjonaliteten. I tillegg, som nevnt ovenfor, inkluderer den ofte en beskrivelse av nødvendig vedlikehold, som tidligere ble gitt i brukerhåndboken (GOST 19.505-79) og/eller vedlikeholdsmanualen (GOST 19.508-79). For øyeblikket brukes dette diagrammet til å kompilere en veiledning for systemadministratoren.

Systemprogrammererens manual bør inneholde følgende avsnitt:

Generell informasjon om programvareproduktet,

struktur,

innstilling,

undersøkelse,

tilleggsfunksjoner,

meldinger til systemprogrammereren.

Generell informasjon om programmet bør inneholde en beskrivelse av formålet med og funksjonene til programmet, samt informasjon om teknisk og programvare som sikrer kjøringen av dette programmet (for eksempel mengden RAM, krav til sammensetningen og parameterne til eksterne enheter, programvarekrav, etc.).

I kapittel Programstruktur informasjon om strukturen til programmet må gis,

henne komponenter, forbindelser mellom komponenter og om forbindelser med andre programmer.

Avsnittet Sette opp programmet bør inneholde en beskrivelse av trinnene for å sette opp programmet for forholdene for praktisk bruk.

Avsnittet Testing av programmet bør inneholde en beskrivelse av måter å kontrollere funksjonaliteten til programmet på, for eksempel testeksempler.

I kapittel Tilleggsfunksjoner en beskrivelse av tilleggsfunksjonene til programmet og hvordan du får tilgang til dem bør gis.

I kapittel Meldinger til systemprogrammereren Tekstene til meldinger utstedt under konfigurasjon og testing av programmet, samt under utførelse av det, må angis en beskrivelse av innholdet og handlingene som må iverksettes som svar på disse meldingene.

11.5. Grunnleggende regler for utarbeidelse av programvaredokumentasjon

Når du utarbeider tekst og grafisk materiale som inngår i programdokumentasjonen, bør du følge gjeldende standarder. Noen bestemmelser i disse standardene er gitt nedenfor.

Design av tekst og grafisk materiale. Tekstdokumenter tegnes på ark i A4-størrelse, mens grafisk banning kan presenteres på ark i A3-størrelse. Marginene på arket bestemmes i henhold til de generelle kravene: venstre - minst 30, høyre - minst 10, topp - minst 15, og bunn - minst 20 mm. I tekstredigerere for utforming av et notat, er sideparametere sortert avhengig av utskriftsenheten. Når du fyller ut dokumenter manuelt, velges sideparametere for enkelhets skyld.

Alle sidene nummereres fortløpende. Tallet er angitt øverst til høyre med et arabisk tall. Sidene inkluderer både ark med tekst og bilder, og ark med applikasjoner. Den første siden anses å være tittelsiden. Sidenummer på tittelside De legger det ikke fra seg.

Navnene på seksjoner er skrevet med store bokstaver i midten av linjen. Avstanden mellom overskrifter og tekst, samt mellom seksjons- og underavsnittsoverskrifter, skal være lik:

når du utfører et dokument ved å skrive - to intervaller;

når det er ferdig håndskrevet - 10 mm;

når du bruker tekstredigerere - bestemt av evnene til redaktøren. Navnene på underseksjoner og avsnitt skal plasseres med avsnittsinnrykk og skriv ut

ute av funksjon med stor bokstav, uten understreking og uten punktum på slutten. Avstand mellom siste linje teksten i forrige seksjon og den påfølgende overskriften, når de er plassert på én side, skal være lik:

når du utfører et dokument ved å skrive - tre intervaller;

når det er gjort håndskrevet - minst 15 mm;

når du bruker tekstredigerere - bestemt av evnene til redaktøren.

Seksjoner og underseksjoner er nummerert med arabiske tall med en prikk. Seksjoner skal ha løpenummer 1, 2 osv. Underseksjonsnummeret inkluderer seksjonsnummeret og løpenummeret til underseksjonen som inngår i denne seksjonen, atskilt med en prikk. For eksempel: 2.1, 3.5. Henvisninger til avsnitt, seksjoner og underavsnitt indikerer, ved å bruke serienummeret til seksjonen eller avsnittet,

eksempel "i Sect. 4", "i klausul 3.3.4".

Teksten til avsnitt skrives ut med 1,5-2 intervaller. Ved bruk av tekstredigering skal høyden på bokstaver og tall være minst 1,8 mm (skrift nr. 11-12).

Oppføringer skal nummereres med arabiske tall med en parentes, for eksempel: 2), 3) osv. - med et avsnittsinnrykk. Det er tillatt å markere en opplisting ved å sette en bindestrek foran et tekstelement eller et symbol som erstatter det i tekstredigering.

Design av tegninger, algoritmediagrammer, tabeller og formler. I samsvar med GOST 2.105-79 " Generelle Krav til tekstdokumenter»-illustrasjoner (grafer, diagrammer, diagrammer) kan gis både i hovedteksten og i vedlegg. Alle illustrasjoner kalles tegninger. Alle figurer, tabeller og formler er nummerert sekvensielt med arabiske tall ( kontinuerlig nummerering) eller innenfor en seksjon (relativ nummerering). I søknaden - i søknaden.

Hver tegning må ha en bildetekst - en tittel plassert under tegningen, for eksempel:

Fig. 12. Hovedmeny vindu form

Alle figurer, tabeller og formler i notatet skal ha lenker i formen: «(fig. 12)» eller «formen til hovedmenyvinduet er vist i fig. 12".

Hvis plassen tillater det, bør figurer og tabeller plasseres umiddelbart etter avsnittet de først er nevnt i, eller så nært som mulig avsnittet på de etterfølgende sidene.

Hvis en tegning opptar mer enn én side, er alle sidene unntatt den første merket med tegningsnummeret og ordet «Fortsettelse». For eksempel:

Ris. 12. Fortsettelse

Figurer bør plasseres slik at de kan sees uten å bla. Hvis slik plassering ikke er mulig, bør bildene plasseres slik at siden må roteres med klokken. I dette tilfellet er den øvre kanten den venstre kanten av siden. Plasseringen og størrelsen på feltene er bevart.

Algoritmediagrammer skal lages i henhold til ESPD-standarden. Tykkelsen på den heltrukne linjen ved tegning av algoritmediagrammer skal være fra 0,6 ... 1,5 mm. Inskripsjoner på diagrammer skal gjøres med tegneskrift, høyden på bokstaver og tall skal være minst 3,5 mm.

Tabellnummeret er plassert til høyre øverste hjørne eller før tabelloverskriften, hvis det er en. Tittelen, bortsett fra den første bokstaven, er skrevet med små bokstaver.

Testresultatene er vist i tabell. 4.

Formelnummeret er plassert på høyre side av siden i parentes på formelnivå. For eksempel:

z: =sin (x)+In (y);

Design av applikasjoner. Hver søknad må begynne med ny side angir ordene «SØKNAD» med store bokstaver og har en tematisk overskrift i høyre hjørne. Hvis det er mer enn én applikasjon, er de alle nummerert med arabiske tall: APPENDIKS 1, APPENDIKS 2 osv. For eksempel:

VEDLEGG 2

Forlikets tittelside og forklarende notat

Figurer og tabeller plassert i vedlegget er nummerert med arabiske tall innenfor hvert vedlegg med tillegg av bokstaven "P". For eksempel:

Ris. Sak 12 - 12. tegning av søknaden; Ris. Sh.2 - 2. bilde av 1. vedlegg.

Hvis applikasjonen inneholder teksten til programmet, er hver fil utformet som en tegning med navnet på filen og dens formål, for eksempel:

Ris. P2.4. Fil menuran.pasprogram for markørbevegelse av hovedmenyen.

Lage en referanseliste. Litteraturlisten skal inneholde alle kilder som brukes. Informasjon om bøker (monografier, lærebøker, manualer, oppslagsverk osv.) skal inneholde: forfatterens etternavn og initialer, tittel på bok, utgivelsessted, forlag, utgivelsesår. Hvis det er tre eller flere forfattere, er det tillatt å angi etternavnet og initialene til bare den første av dem med ordene "osv." Forlaget må siteres i sin helhet i nominativ tilfelle: forkortelse av navnet på bare to byer er tillatt: Moskva (M.) og St. Petersburg

Informasjon om en artikkel fra et tidsskrift må inneholde: forfatterens etternavn og initialer, navnet på artikkelen, publikasjon (magasin), serie (hvis noen), utgivelsesår, volum (hvis noen), nummer på publikasjonen ( magasin) og sidetall som artikkelen er plassert på.

11.6. Regler for utarbeidelse av beregning og forklarende notater for kursutforming

Når du utarbeider forklarende notater, bør du følge GOST 7.32-91 (ISO 596682) "Rapport om forskningsarbeid. Struktur og designregler." I samsvar med denne standarden må et tekstdokument av denne typen inneholde:

tittelside,

abstrakt,

innhold,

introduksjon,

hoveddelen,

konklusjon,

liste over kilder som er brukt, inkludert litteratur,

applikasjoner.

Tittelsiden er utarbeidet i samsvar med GOST 19.104-78 "Unified system of program documentation. Grunnleggende inskripsjoner" (Fig. 11.1).

Den andre siden er et sammendrag eller sammendrag av programvareproduktet som utvikles. Sammendraget i komprimert form skal inneholde informasjon om dokumentets volum, antall illustrasjoner, vedleggstabeller etc., samt en liste søkeord og hovedbestemmelsene i dokumentet. For eksempel for en rapport om forskningsarbeid: beskrivelse av forskningsobjektet, mål for arbeidet, forskningsmetoder og utstyr, oppnådde resultater, anbefalinger for gjennomføring osv. Merknaden beskriver også kort formål og trekk ved utviklingen, men den inneholder vanligvis ikke informasjon om volum osv.

Tredje side - innhold, inkludert: introduksjon, navn på alle seksjoner, underavsnitt, avsnitt, konklusjon, referanselister og bruksområder angir sidetall. Verken merknaden eller abstraktet eller selve innholdet er nevnt i innholdsfortegnelsen.

Deretter følger delene av dokumentet i rekkefølgen bestemt av logikken i presentasjonen av materialet. Dette kan etterfølges av vedlegg som inneholder materiale som ikke er inkludert i dokumentet på grunn av dets begrensede volum, men interessant for en dypere forståelse av materialet som presenteres.

Som et eksempel, se innholdsfortegnelsen i forklarende notat for prosjektet for kurset "Programmeringsteknologi".

Introduksjon................................................. ...................................................... ............................................................ ..........
1.Valg av teknologi, språk og programmeringsmiljø......................................... ............................................
2.Analyse og avklaring av krav til programvareproduktet.................................. ............................
2.1.Analyse av og valg av strukturer
data for lagring ........................................................ ...................................................... ............................
2.2.Valg av metoder og utvikling av grunnleggende algoritmer for å løse problemet...................................
3. Utvikling av et strukturelt diagram av et programvareprodukt......................................... ............................
4. Utforming av brukergrensesnitt......................................... ......................................................
4.1.Konstruksjon av en dialoggraf........................................... ............................................................ ............... .......
4.2.Utvikling av informasjon input-output skjemaer......................................... ............................................
5. Utforming av domeneklasser................................................... ............................................................... .....
5.1.Konstruere et klassediagram......................................................... ........................................................ .........
5.2 Avklaring av strukturen til domeneklasser
og utvikling av metodealgoritmer......................................... ................................................................ ...........
6.Valg av teststrategi og testutvikling......................................... ........................................
Konklusjon................................................. ................................................................ ........................................................
Bibliografi................................................ . ................................................................ ............................................
Vedlegg 1. Tekniske spesifikasjoner.................................................. ...................................................... ............ ..
Vedlegg 2. Brukerveiledning.................................................. ......................................................

Kontrollspørsmål

1. Nevn hovedtypene programvaredokumentasjon. Beskriv hver av dem. I hvilke tilfeller brukes de?

2.Hva skal beskrives i forklaringen? Hvem er den beregnet på? Hvorfor beskriver forklarende notater vanligvis ikke bare beslutningene som er tatt, men også de avviste alternativene?

3.Hvem er brukerveiledningen ment for? Hva skal den inneholde? I hvilke situasjoner leser du bruksanvisningen? Tenk tilbake på brukermanualene du har lest. Hva likte du ikke med dem?

APPLIKASJON

Unified Modeling Language (UML) notasjonssystem

Unified Modeling Language UML – faktisk standard middel beskrivelser av prosjekter laget ved hjelp av en objektorientert tilnærming. Programvareprosjektmodellen, som ment av språkforfatterne, kan inkludere et stort nummer av diagrammer forskjellige typer, ved hjelp av et enhetlig notasjonssystem. Blant diagrammene er de mest brukte:

bruk kasusdiagrammer eller presedenser (bruker case-diagrammer) - viser hovedfunksjonene til systemet for hver type bruker;

klassediagrammer(klassediagrammer): kontekstuelle, beskrivelser av grensesnitt og implementeringer - demonstrere relasjonene mellom klasser med hverandre;

aktivitetsdiagrammer(aktivitetsdiagrammer) - representerer et diagram over kontrollflyter for å løse en bestemt oppgave ved hjelp av individuelle handlinger; de tillater tilstedeværelsen av parallelle og/eller alternative handlinger;

interaksjonsdiagrammer(interaksjonsdiagrammer) av to alternative typer:

a) sekvensdiagrammer (sekvensdiagrammer) - vis den tidsordnede interaksjonen til objekter under utførelsen av en brukssak,

b) samarbeidsdiagrammer(samarbeidsdiagrammer) - gi samme informasjon som sekvensdiagrammer, men i en form som lar deg bedre representere klassenes ansvar som helhet;

objekttilstandsdiagrammer(statechart-diagrammer) - viser tilstandene til et objekt og betingelsene for overganger fra en tilstand til en annen;

pakkediagrammer(pakkediagrammer) - demonstrere forholdet mellom sett med klasser kombinert til pakker;

komponentdiagrammer(komponentdiagrammer) - vis hvilke programvarekomponenter inneholder programvare og hvordan disse komponentene er relatert til hverandre;

plasseringsdiagrammer(distribusjonsdiagrammer) - lar deg koble til programvare- og maskinvarekomponenter i systemet.

Supplementer til diagrammer er formaliserte og uformelle tekstbeskrivelser, kommentarer og ordbøker.

Når du konstruerer disse og andre diagrammer, brukes et enhetlig notasjonssystem. Betegnelsene til presedensdiagrammene er gitt i tabell. Punkt 1, klasse- og pakkeskjemaer - i tabell. Punkt 2, interaksjonsdiagrammer - i tabell. P3, diagrammer over aktiviteter og tilstander til objektet - i tabell. Punkt 4, diagram over komponenter og plassering - i tabell. S.5. Om nødvendig er det tillatt å bruke betegnelsene til noen diagrammer på andre.