Registrering av brukerhåndboken for GOST. LLC "Teknisk dokumentasjon

Hei igjen, kjære habralyud!

Jeg fortsatte innlegget mitt og bestemte meg for å skrive hvordan man best kan lage instruksjoner for brukere og administratorer.

Alle som er interessert ber jeg om habrakat.

KYSSE

Keep It Simple Stupid-prinsippet er velkjent innen programmering, men av en eller annen grunn brukes det sjelden til å skrive instruksjoner og retningslinjer, foretrekker å spre tanker langs et tre. I 70 % av situasjonene er denne dokumentasjonen kun nødvendig for å børste av våre spreke regulatorer, men samtidig glemmer de at denne dokumentasjonen må fungere, og folk som ikke alltid er teknisk kyndige og kompetente innen informasjonssikkerhet.

Til å begynne med vil jeg skrive noen regler som vil hjelpe deg med å lage et fungerende og praktisk dokument:

1. Prøv å skille instruksjoner for brukere fra instruksjoner for administratorer og sikkerhetsansvarlige. og førstnevnte skal ikke inneholde lenker til sistnevnte (de kan inneholde referanser til hverandre).
2. Gjør trinnvise instruksjoner som "ta det og gjør det". Det vil si at instruksjonene skal beskrive handlingsalgoritmen til den som den er rettet mot.
3. Beskriv hvert punkt som en egen handling med obligatorisk angivelse av ansvarlig person og kontakter, om nødvendig.
4. For større klarhet kan du i tillegg tegne et flytskjema over handlinger i instruksjonen. Dette vil hjelpe brukeren til tydelig å forstå og evaluere handlingene, samt forklare algoritmen for deg under trening.
5. Det psykologiske øyeblikket - instruksjonen vil være dårlig utført og fungere hvis algoritmen ikke er tydelig og enkelt forklart for brukerne på fingrene og eksempler. Derfor - IKKE GLEM Å LÆRE!

Eksempel på instruksjon for brukere

Nedenfor er et eksempel på instruksjoner for å sette opp en brukerkonto på et bedriftsnettverk.

Tydelig skjerm / oversiktlig skrivebord

Spesifisiteten til russiske organisasjoner som har jobbet siden sovjettiden og med den samme sofistikerte erfaringen til ansatte er slik at skrivebordet deres som regel er overfylt med papirer. Datamaskinen slår seg noen ganger ikke av og blokkerer ikke, selv når de går hjem. Nylig så jeg personlig, mens jeg gikk forbi et kommunalt foretak sent på kvelden, at en monitor med et Vord-dokument åpent brant bak de åpne persienner i en låst bygning.
Brukere er noen ganger uvitende om mulige utilsiktede informasjonslekkasjer. Selv om den ikke er konfidensiell, kan den kun være til intern bruk. Men dette gir en forståelse av at denne organisasjonen ikke bryr seg om deres sikkerhet og kan gjøre dette med konfidensielle filer. Og det er også mulig det vil være informasjon som ennå ikke er klassifisert som lukket, men som allerede eksisterer i organisasjonens interne sirkulasjon.

Et godt eksempel på beste praksis her er policyen for klar skrivebord og klar skjerm. De kan beskrives på samme måte som jeg ga et eksempel tidligere, men det vil se litt dumt ut, siden handlingene der er veldig enkle. Bedre å bare gjøre det til et sett med regler:

P.S. Innlegget inneholder skjermbilder av faktisk implementerte og fungerende instruksjoner og retningslinjer. Alle sammentreff med eksisterende organisasjoner er tilfeldige. Alle avdelings- og byrånavn er endret.

Brukermanual som programvare (operativ) brukerdokumentasjon

Dokumentet "Brukerveiledning" refererer til pakken med driftsdokumentasjon. Hovedformålet med brukermanualen er å gi brukeren nødvendig informasjon for selvstendig arbeid med programmet eller automatiserte systemet.

Derfor bør brukerveiledningsdokumentet svare på følgende spørsmål: hva slags program er det, hva det kan gjøre, hva som er nødvendig for å sikre at det fungerer korrekt og hva du skal gjøre i tilfelle systemfeil.

Dokumentasjon: programvare / drift / brukerdokumentasjon

Punkt: program, programvarekomponent i et kompleks eller system

Publikum: brukere av programmet, det vil si personer som bruker det til å løse sine egne anvendte problemer

Oppgaver: å gi brukerne muligheten til å mestre og bruke programmet fullt ut uavhengig

De veiledende standardene for å lage et brukerveiledningsdokument kan være som følger: RD 50-34.698-90 i p.p. 3.4. "Brukerhåndboken" og GOST 19.505-79 brukerhåndbok. Krav til innhold og design".

Følgende hoveddeler i brukerhåndboken kan skilles fra hverandre:

Formålet med systemet;

Systemapplikasjonsbetingelser;

Forberede systemet for arbeid;

Beskrivelse av operasjoner;

Nødsituasjoner.

Formålet med systemet

Denne delen av brukerhåndboken bør inneholde informasjon om formålet med systemet, dets mål og mål.

Eksempel:

"Bedriftens intranettportal er designet for å forbedre bedriftskulturen for å organisere effektiv interaksjon mellom ansatte.

Hovedmålet med havnen er å skape et enhetlig informasjonsrom for bedriften og optimalisere arbeidet til ansatte ved å lette kommunikasjonen mellom dem og optimalisere en rekke forretningsprosesser."

Systemapplikasjonsbetingelser

Denne delen av brukerveiledningen bør inkludere alle de faktorene som er nødvendige for riktig drift av systemet. Her kan du skille mellom flere underseksjoner:

Maskinvarekrav - her kan du inkludere krav til konfigurasjonen av brukerens datamaskin, programvare nødvendig for driften av systemet, samt tilgjengeligheten av tilleggsutstyr (skriver, skanner, etc.), om nødvendig;

Brukerkvalifikasjoner - denne underdelen bør inneholde krav til brukerens ferdigheter og kunnskaper ( eksempel: "Brukere må være kjent med Windows-operativsystemet.");

Klargjøring av systemet for arbeid

Denne delen av brukerveiledningen bør inneholde trinnvise instruksjoner for å starte applikasjonen. Stadiet for å forberede systemet for drift inkluderer installasjon av tilleggsapplikasjoner (om nødvendig), identifikasjon, autentisering, etc.

Beskrivelse av operasjoner

Dette er hoveddelen av brukerveiledningen, som inneholder trinnvise instruksjoner for å utføre en handling av brukeren.

Hvis driften av et automatisert system påvirker en hel forretningsprosess, er det i brukermanualen, før du beskriver operasjonene, å gi informasjon om denne prosessen, dens formål og deltakere. En slik løsning lar en person tydelig forestille seg sin rolle i denne prosessen og funksjonene som er implementert for ham i systemet.

Videre i dokumentet skal brukerveiledningen gi en beskrivelse av funksjonene delt inn i separate operasjoner. Det er nødvendig å fremheve underavsnitt som beskriver funksjonene til denne prosessen, og handlingene som må utføres for å utføre dem.

Eksempel:

"4.1 Prosjektgodkjenning

Denne prosessen er designet for å organisere arbeidet til ansatte som er involvert i utviklingen og godkjenningen av prosjektet.

Forfatteren av prosjektet oppretter en oppføring i systemet og legger ved en pakke med nødvendig dokumentasjon, deretter sendes prosjektet inn for godkjenning av lederne. Etter å ha gjennomgått prosjektet, kan ledere bekrefte det eller sende det til forfatteren for revisjon.

4.1.1 Opprett et prosjekt

For å opprette et prosjekt, klikk på "..."-knappen på "..."-panelet og fyll ut følgende felt i skjemaet som vises:

Navn på prosjektet;

Beskrivelse av prosjektet;

Følgende felt fylles ut automatisk:

Prosjektopprettelsesdato - gjeldende dato;

Jo mer detaljerte handlinger med systemet er beskrevet, jo færre spørsmål vil brukeren ha. For en enklere forståelse av alle prinsippene for å jobbe med programstandardene i dokumentet Brukerveiledning, er det tillatt å bruke diagrammer, tabeller, illustrasjoner som viser skjermformer.

For store automatiserte systemer anbefales det å lage en egen manual for hver brukerkategori (bruker, moderator osv.). Hvis det tildeles flere brukerroller i arbeidet med systemet, er det lurt å plassere en tabell over funksjonsfordeling mellom roller i brukerveiledningen.

Nødsituasjoner

Denne delen av dokumentet Brukerhåndbok bør inneholde trinnvise instruksjoner for brukerens handlinger i tilfelle feil i systemet. Hvis brukeren ikke har blitt presentert med spesielle krav til administrasjon av operativsystemet osv., kan du begrense deg til setningen "I tilfelle feil eller funksjonsfeil i systemet, må du kontakte systemadministratoren."

Metodikk og stil for presentasjon av brukermanualen

Brukermanualen kan enten være en kort veiledning til hovedfunksjonaliteten til programmet, eller en komplett veiledning. Metoden for å presentere materialet i dette tilfellet vil avhenge av omfanget av selve programmet og kundens krav.

Avhengig av funksjonene i programmet og målgruppen, kan brukermanualen om måten å presentere materialet på ligge nær en lærebok eller omvendt en oppslagsbok. Rekkefølgen for presentasjon av materialet i brukerhåndboken bestemmes tilpasset perspektiv programmer.

Hvis programmet er et verktøy som lar deg løse praktiske problemer fra et begrenset sett, gir håndboken typiske prosedyrer for å løse hver av dem. For eksempel må en bruker av en e-postklient vite hvordan man skriver og sender en melding, hvordan man laster ned nye meldinger fra serveren, hvordan man svarer på en melding osv. Hver av disse handlingene kan dekomponeres i sekvensielle elementære trinn, i hvert fall for typiske situasjoner. I et stort program av lignende tilpassede oppgaver det kan være mange, men ikke uendelig mange. Brukerhåndboken, bygget på prinsippet om brukeroppgaver, ligner en lærebok, selv om den som regel mangler det metodiske apparatet som er iboende i lærebøker: testoppgaver, spørsmål, øvelser.

Hvis programmet er et miljø der brukeren kan løse oppgavene som er satt av ham på egen hånd, bør brukermanualen være nærmere referansen. Den bør konsekvent og systematisk beskrive alle funksjonene til programmet og rekkefølgen på deres anvendelse. Hva de skal gjøre med dem, hva de skal dirigere, vil brukeren tenke selv (eller melde seg på kurs). Så i brukermanualen for den grafiske editoren finner vi en beskrivelse av alle grafiske primitiver, verktøy, filtre, men det vil ikke direkte si hvordan en bygning, en bil eller for eksempel en hund skal skildres. Brukeren vet enten hvordan den skal tegnes eller ikke.

Andre tilpassede perspektiver er også mulig. Det er programmer der brukeren kontrollerer tilstanden til et objekt, for eksempel et industrianlegg. Deretter er brukermanualen strukturert i henhold til prinsippet om en tabell: budskapet til programmet er reaksjonen eller mulige reaksjoner fra brukeren.

Dersom brukeren bruker programmet til å løse problemer innen ikke-trivielle fagområder, anbefales det på det sterkeste å inkludere en konseptuell del i brukermanualen. Den bør beskrive måten implementert i programmet for å representere objekter fra den virkelige verden, slik at brukeren har en god forståelse av hvilke av dem og på hvilket abstraksjonsnivå han kan arbeide.

retningslinjer for ESPD og IEEE Std 1063-2001, tatt i betraktning "Kagarlitsky-manifestet". Det er vist at den generelle strukturen til brukerhåndboken, satt sammen i samsvar med kravene til det "utdaterte" GOST 19-systemet, betydelig overstiger strukturen til håndboken anbefalt av den ultramoderne IEEE Std 1063-2001. Utgave av 20.06.2018.

Hvordan skriver jeg en brukermanual? Del I - generalisert struktur av brukerhåndboken i samsvar med GOST-system 19 og dens sammenlignende analyse med anbefalingene fra IEEE Std 1063-2001

Opprettet 02.11.2005 11:14:22

Når håpet dør, kommer fortvilelsen.

Klokt latinsk ordtak

Hvordan skriver jeg en guide? Lag en trelignende brukerhåndbok og fullfør deler av den. Og all kjærligheten.

Hvor kan jeg finne strukturen til delene i brukerhåndboken? Med manualer på (bruksanvisning for) og på (), er alt mer eller mindre oversiktlig. Men dokumentet "Brukerhåndbok" for selve programmet er fraværende som en klasse i GOST-ene til det 19. systemet.

Hvilket innhold skal brukes for å fylle ut delene av brukerhåndboken? Hvordan være? Det viktigste er ikke å fortvile.

Mål og formål med artikkelen

Som alltid - prøv å gjøre livet enklere for brukermanualen til programmet.

• analysere eksisterende og utvikling, identifisere fordeler og ulemper ved hvert dokument separat;
• utlede en viss generalisert struktur av brukerhåndboken i samsvar med GOST-system 19 fra det eksisterende settet med operasjonelle programdokumenter;
• sammenligne den med strukturen anbefalt av IEEE Std 1063-2001;
• og alle andre oppgaver migrert til den andre delen av artikkelen ...

Merknad fra 10. juli 2014 - I februar 2005 ble det kanskje ikke engang utført en komparativ analyse, men snarere sammenlignende tester, som viste den udiskutable overlegenheten til GOST 19-standardsystemet over de borgerlige og den nesten fullstendige inkonsekvensen til sistnevnte. .

Spørsmål som skal besvares av brukermanualen

Presenter et elektronisk leketøy som er ukjent for barnet ditt. Listen over spørsmål vil være omtrent slik (med mindre den går i stykker med en gang):

• hva er det;
• og hva kan de gjøre;
• og hva de ikke burde gjøre (blant de begavede);
• hva som skal til for at det skal fungere;
• og hva som er inne i ham (hos barn som er utsatt for dypt);
• men hvordan konfigurere den til å fungere slik jeg vil;
• hvordan sjekke det, om det fungerer eller ikke;
• og hva og hvor du skal trykke;
• og hva annet kan det gjøre;
• og hva står det om du trykker feil?

Rekkefølgen av spørsmål kan være svært variert. Og et dokument kalt «Brukerveiledning» skal gi svar på alle spørsmålene som stilles. Det er enkelt. Djevelen er ikke så forferdelig som han er malt.

Brukerveiledning: Fire kilder og fire komponenter

Vi har:

• Kagarlitskys "metagide";
• state-of-the-art IEEE Std 1063-2001, "IEEE Standard for Software User Documentation";
• klassiske russiske GOST-er av det 19. systemet, som inkluderer følgende dokumenter av "beskrivende" karakter:

De fire siste fra listen er driftsprogramdokumenter.

Kanskje finnes det andre dokumenter, men forfatteren, som rotet grundig i Runet-deponiet, har ennå ikke klart å få tak i noe mer passende. Yandex oppdaget i innvollene en annen side med tittelen "How to Make a Good User Manual", forfatteren som kaller seg en amerikaner B stil (som John P. Morgan). Den to sider lange «formaningen» med jubel ble umiddelbart sendt til søppelbøtta.

Kagarlitskys manifest

Kagarlitskys metagayde virket lovende. Bare forfatteren av denne artikkelen skjønte ikke hva et "metagide" er, så han våget å kalle metagidet et "manifest". Og han syndet ikke mot sannheten (men det ble avslørt senere - nedenfor).

(sitater fra Kagarlitskys manifest)

Vi prøvde å bringe inn i et enkelt system hele settet med standardkrav som, fra vårt ståsted, bør presenteres for teknisk dokumentasjon: manualer, oppslagsverk osv. Ved å gjøre det tok vi utgangspunkt i standarder (!!!)GOST , Microsoft-standarder, erfaringen til våre ansatte og andre utviklere av teknisk dokumentasjon.

En oppmuntrende start.

Den tekniske dokumentasjonen inkluderer to sentrale deler, som vi vil kalle henholdsvis brukermanualen og brukerens referanse, eller kort: manualen og referansen (i analogi med de engelske frasene User "s Guide and User" s Reference). De kan utarbeides som separate dokumenter (for store programvareprodukter), eller tvert imot eksistere i en integrert form. Det er kanskje ikke engang en klar grense mellom dem: en enkelt tekst er i stand til å kombinere funksjonene til en veiledning og funksjonene til en oppslagsbok.

Håndboken og referansen er ikke så mye deler av dokumentasjonen som de inneholder to tilnærminger til å beskrive et programvareprodukt.

Konseptmessig, så konseptmessig, er det bare guttene som begynner å bli nervøse. Ledelse er ikke et konsept, det er det.

Vår oppgave er ikke så mye å fortelle hvordan dokumentasjonen ser ut, men heller å å gi spesifikke anbefalinger for utviklingen ... Alle vet hvilke problemer som oppstår i prosessen med å skrive en sammenhengende tekst av et stort volum - hvordan komme i gang, med hvor du skal begynne, hvordan ordne materialet ... Denne tilnærmingen oppmuntrer oss til å se i normene vi forkynner ikke kaotisk deres liste, og det hierarkiske systemet ...

En stjerne ved navn Nadezhda skinte på himmelen - nå vil den respekterte Mr. Kagarlitsky gi oss, de rettighetsløse, en omfattende hierarkisk struktur av brukermanualer til alle tider og folkeslag. Kom igjen?!

Før du fortsetter med utviklingen av dokumentasjon som sådan, er det nødvendig å skissere og planlegge presentasjonens generelle logikk. Det kan virke som om sjangeren med teknisk dokumentasjon er ekstremt enkel: Tross alt er oppgaven "bare" å informere brukeren om noe informasjon om produktet. Men hvis du går ut fra dette i arbeidet ditt, vil du lage eksempler på dokumentasjon som er helt ubrukelig eller neppe egnet til praktisk bruk, selv om all nødvendig informasjon finnes der. Din oppgave er å lede brukeren gjennom passet, det vil si å finne et sted i fjellkjeden, som selv med vanskeligheter fortsatt er farbar for din "avdeling".

Det er synd ... Men alt begynte bra. Fra standarder GOST"-" standarder "- tilgi Mr. Kagarlitsky for tautologien. Først nå er det ingen løsning på det første problemet som er stilt av forfatteren av denne artikkelen i det syttito sider lange manifestet (Arial "om 12pt). Kjære forfatter av manifestet, bare sett vår oppgave ... Vel, det er ingen profet i hans eget land. Kanskje finnes det en profet i det borgerlige fedrelandet?

Brukerveiledning til IEEE Std 1063-2001 "IEEE Standard for Software User Documentation"

Utenlandsk "profetisk" dokument IEEE Std 1063-2001 (IEEE i vanlige mennesker - "ay-ay-ay") i underavsnitt 1.2 (Puprose) inneholder følgende linje:

Denne revisjonen stiller krav til struktur, informasjonsinnhold og format for både trykt og elektronisk dokumentasjon.

Etter forfatterens forståelse er formålet (hensikt, hensikt, hensikt, ambisjon) med IEEE Std 1063-2001-dokumentet "å gi krav til struktur, innhold, (design) samt trykt brukerdokumentasjon for programvare." Vel, det er greit. Hvilken struktur i brukerhåndboken foreslår IEEE Std 1063-2001?

Strukturen til IEEE Std 1063-2001 Brukerhåndbok

En valgfri generisk brukermanualstruktur finnes i tabellen fra strukturen til i IEEE Std 1063-2001:

Identifikasjonsdata (pakkeetikett / tittelside)
Innholdsfortegnelse		Ja, i dokumenter på mer enn åtte sider etter identifikasjonsdata
Liste over illustrasjoner
Konsept for operasjoner
		Ja (instruksjonsmodus)
		Ja (referansemodus)
		Ja, hvis dokumentasjonen inneholder ukjente termer
Relaterte informasjonskilder
Navigasjonsfunksjoner
		Ja, hvis dokumenter på mer enn 40 sider
Søkeevne		Ja, i elektroniske dokumenter

For formålene med denne standarden brukes følgende ikke-obligatoriske nomenklatur for de strukturelle delene av. Et trykt dokument er strukturert i logiske enheter kalt kapitler, delt inn i emner, som kan deles inn i underemner, og skrives ut på fysiske enheter kalt sider.

Flott. IEEE Std 1063-2001 foreslår "ta og del alt" - deler opp deler av håndboken i kapitler, emner, underemner, etc. Og alle vil være glade.

De uthevede delene er av praktisk interesse (innenfor rammen av artikkelens mål). La oss se hvordan du deler deler av brukerhåndboken inn i mindre strukturelle enheter og hvilket innhold som skal fylle disse strukturelle enhetene.

Introduksjon

Hvilken informasjon bør inkluderes i introduksjonsdelen av IEEE Std 1063-2001? Men hva

Innledningen skal beskrive den tiltenkte målgruppen, omfanget og formålet for dokumentet og inneholde en kort oversikt over programvarens formål, funksjoner og driftsmiljø.

Vel, det er flott. Strukturen til introduksjonsdelene begynner å ta form.

Informasjon for bruk av dokumentasjonen

Dokumentasjonen skal inneholde informasjon om hvordan den skal brukes (for eksempel hjelp til hjelp), og en forklaring av notasjonen (en beskrivelse av formater og konvensjoner - se 5.8). Minst ett dokument i et dokumentsett skal identifisere alle dokumenter i settet etter tittel og tiltenkt bruk, inkludert anbefalinger om hvilke medlemmer av publikum som bør konsultere hvilke deler av dokumentasjonen. I dokumentsett som inneholder mange bind eller produkter, kan denne informasjonen gis i et eget "veikart" eller veiledning til dokumentsettet. Dokumentasjon kan omfatte identifikasjon og diskusjon av merkbare endringer fra forrige versjon av dokumentsettet og programvaren.

En veldig nyttig del (i utviklingen av brukermanualen). Lederguide.

Konsept for operasjoner

Dokumentasjonen skal forklare den konseptuelle bakgrunnen for bruk av programvaren, ved bruk av metoder som en visuell eller verbal oversikt over prosessen eller arbeidsflyten; eller teorien, begrunnelsen, algoritmene eller det generelle operasjonskonseptet. Forklaringer av driftskonseptet bør tilpasses brukernes forventede kjennskap til eventuell spesialterminologi for brukeroppgaver og programvarefunksjoner. Dokumentasjon skal relatere hver dokumentert funksjon til den overordnede prosessen eller oppgavene. Konseptuell informasjon kan presenteres i ett avsnitt eller umiddelbart før hver gjeldende prosedyre.

Konseptuell informasjon er absolutt viktig.

Prosedyrer

Oppgaveorientert instruksjonsmodusdokumentasjon skal inkludere instruksjoner for rutinemessige aktiviteter som brukes på flere funksjoner:

Programvareinstallasjon og de-installasjon, hvis utført av brukeren

Orientering om bruk av funksjonene til det grafiske brukergrensesnittet (se 5.6)

Få tilgang til, eller logg på og logg av programvaren

Navigering gjennom programvaren for å få tilgang til og gå ut av funksjoner

Dataoperasjoner (skriv inn, lagre, les, skriv ut, oppdater og slett)

Metoder for å avbryte, avbryte og starte operasjoner på nytt

Disse vanlige prosedyrene bør presenteres én gang for å unngå redundans når de brukes i mer komplekse funksjoner.

Og konkterika gikk. Godt gjort, borgerlig!

Informasjon om programvarekommandoer

Dokumentasjonen skal forklare formatene og prosedyrene for brukeroppgitte programvarekommandoer, inkludert nødvendige parametere, valgfrie parametere, standardalternativer, rekkefølge av kommandoer og syntaks. Dokumentasjon kan gis om utvikling og vedlikehold av makroer og skript. Referansemodusdokumentasjon skal inneholde en referanseliste over alle reserverte ord eller kommandoer. Eksempler skal illustrere bruken av kommandoer. Dokumentasjonen skal forklare hvordan man kan avbryte og angre operasjonen under utførelse av en kommando og hvordan man starter den på nytt, hvis mulig. Dokumentasjonen skal beskrive hvordan man gjenkjenner at kommandoen er vellykket utført eller unormalt avsluttet.

Feilmeldinger og problemløsning

Dokumentasjonen bør behandle alle kjente problemer ved bruk av programvaren i tilstrekkelig detalj slik at brukerne enten kan komme seg fra problemene selv eller tydelig rapportere problemet til teknisk støttepersonell. Referansemodusdokumentasjon skal inkludere hver feilmelding med en identifikasjon av problemet, sannsynlig årsak og korrigerende handlinger som brukeren bør iverksette. Et hurtigreferansekort kan adressere feilmeldinger ved å henvise brukeren til mer detaljert referansedokumentasjon. Dokumentasjonen for å løse problemer skal også inneholde kontaktinformasjon for rapportering av problemer med programvare eller dokumentasjon og forslag til forbedringer.

Konklusjoner om IEEE Std 1063-2001

Men lykken viste seg å være ufullstendig ... Strukturen til delene av det første nivået i manualen er vist i tabellen eksplisitt. Og så - "min kjære, gode, gjett deg selv" ("gjett, sier de, deg selv"). IEEE Std 1063-2001 "gir selvfølgelig krav til strukturen", men tilbyr ikke eksplisitt strukturer brukermanualer opp til den anbefalte GOST 2.105 på det fjerde hekkenivået.

Anbefalinger som "Dokumentasjon skal forklare ...", "Eksempler skal illustrere ...", "Dokumentasjon skal beskrive ..." og lignende er absolutt tidstestet. I brukermanualen er det nødvendig å forklare, og illustrere, og beskrive – ingen tvil om det. Men alt dette er forståelig for geiten, og det er stavet i GOST-ene til det 19. systemet.

Så det er usannsynlig å utvikle brukermanualer utelukkende basert på anbefalingene fra IEEE Std 1063-2001. Det er minst to grunner:

• mangelen på en klart definert brukermanualstruktur i IEEE Std 1063-2001;
• "Overfladiskhet" IEEE Std 1063-2001, mangel på "dekningsbredde" og "studiedybde".

Mangelen på en tydelig regulert struktur i brukerhåndboken vil gjøre det mulig BEHANDLE, se i det minste. Den stakkars utvikleren vil på forespørsel fra kunden bli tvunget til å endre plasseringen av delene av brukerhåndboken fra dag til dag (garantert minimum, innhentet empirisk).

Mangelen på en veldefinert struktur blir til kaos så snart nivået på hekkingen faller til det andre eller tredje. Brukeren vil rett og slett kaste en slik guide til helvete og kalle forfatteren en nerd.

Ifølge forfatteren er anbefalingene til IEEE Std 1063-2001, utviklet med deltakelse av hundrevis av utenlandske spesialister, veldig, veldig overfladiske. En utvikler som arbeider i samsvar med IEEE Std 1063-2001, vil ikke kunne dekke de maksimale "egenskapene" som er iboende i programmet. Mange av dem er rett og slett ikke stavet i IEEE Std 1063-2001. Det er ingen "dekningsbredde" og "dybde av utdypning" som er karakteristiske for innenlandske dokumenter.

I den ekstreme delen av denne artikkelen er det en korrespondansetabell mellom GOST 19 og IEEE Std 1063-2001, som forfatteren av artikkelen begynte å kompilere, for så å droppe den og ikke sjekke den. Og la alle trekke sine egne konklusjoner. Og kanskje vil han korrigere forfatteren på en eller annen måte.

Brukerdokumenter i henhold til GOST 19 (ESPD)

I motsetning til den ultramoderne borgerlige IEEE Std 1063-2001, inneholder de eldgamle, mange misbrukte innenlandske standardene til det 19. systemet (Unified system of program documentation - ESPD) ikke lange argumenter om hva og hvordan som skal forklare, illustrere og beskrive brukerhåndboken, men spesifikke krav til struktur og innhold i bruker(drifts)dokumenter.

Listen over GOSTs 19 av "beskrivende" karakter, på grunnlag av hvilken det er mulig, uten videre, å danne en klar struktur av deler av hvert av de "beskrivende" dokumentene, er gitt i Kilder-delen. Hovedteknikken - detaljering - er beskrevet i detalj i artikkelen "". Videre - dannet ved å "detaljere" strukturen til deler av dokumenter i samsvar med GOST-er fra listen.

Strukturen til delene av programbeskrivelsen i henhold til GOST 19.402-78

Strukturen til delene av søknadsbeskrivelsen i henhold til GOST 19.502-78

Strukturen til delene av systemprogrammererens håndbok i samsvar med GOST 19.503-79

Strukturen til delene av programmeringshåndboken i samsvar med GOST 19.504-79

Strukturen til delene av brukerhåndboken i henhold til GOST 19.505-79

Konklusjoner i henhold til GOST 19.xxx

Verken, eller, sett individuelt, kan skryte av tilstrekkelig fullstendighet av strukturen.

Men strukturene til "beskrivende" dokumenter av GOST 19 har både helt identiske (i teksten til titlene) og lignende i teksten til titlene til seksjoner og underseksjoner. Identiske seksjoner inkluderer for eksempel "" seksjonene som vises i alle dokumenter iht. Underavsnittene "Formål med programmet" og "" kan klassifiseres som like (faktisk - identiske).

Hvorfor ikke prøve å kombinere alle de "beskrivende" dokumentene? Kombinere identiske og lignende deler av dokumenter, fremheve spesifikke deler? Kanskje det vil være mulig å kvitte seg med ufullstendigheten til GOST 19.505-79, GOST 19.504-79 og GOST 19.503-79 og få en generalisert struktur av et "beskrivende" dokument og kalle selve dokumentet en programbrukerveiledning?

GOST 19.xxx tillate "å introdusere flere seksjoner eller å kombinere separate seksjoner", samt "introdusere nye". I følge GOST 19.101-77 "Det er tillatt å kombinere visse typer operasjonelle dokumenter (bortsett fra og). Behovet er angitt i. Det sammenslåtte dokumentet tildeles også betegnelsen på ett av de sammenslåtte dokumentene. De kombinerte dokumentene må inneholde informasjon som må inkluderes i hvert kombinerte dokument [fra paragraf 2.6 i GOST 19.101-77] "

Ikke før sagt enn gjort. Bare vi vil bryte GOSTs og lage et enhetlig dokument kalt "Brukerveiledning".

Generell struktur av brukerhåndboken i samsvar med GOST-system 19

Ved å slå sammen strukturene til "beskrivende" dokumenter til GOST-system 19 til en enkelt struktur, fjerne "unødvendige" seksjoner med samme navn, slå sammen lignende seksjoner, ble den generelle strukturen til programmets brukerhåndbok dannet. Platen inneholder og " * »Merker seksjonene som vises i hvert enkelt dokument.

GOST 19.xxx - generalisert struktur av manuelle seksjoner	GOST 19.402-78	GOST 19.502-78	GOST 19.503-79	GOST 19.504-79	GOST 19.505-79
merknad
Formålet med dokumentet
Generell informasjon om programmet
Betegnelse og programmer
som programmet er skrevet på
Informasjon om formålet med programmet
Informasjon tilstrekkelig for forståelse og dens
Funksjoner i programmet
Klasser av oppgaver som skal løses
Beskrivelse av oppgaver
Metoder for problemløsning
Tidskarakteristikker
Arbeidstid
Bruksvilkår for programmet
Informasjon om og sikring av gjennomføring av programmet
Typer som brukes når programmet kjører
Krav til sammensetning og parametere
Beskrivelse av den logiske strukturen
Programmer
Metoder som brukes
Informasjon om
Informasjon om programmet
Informasjon om og
Inndatadetaljer
Utdatadetaljer
Format, beskrivelse og utdatametode
Funksjonsvalg
Illustrerende eksempler
Beskrivelse av måtene å sjekke programmet på
Testtilfeller
Kjør metoder
resultater
Programutførelse
Lansering av programmet
Inngangspunkter til programmet *
Metoder for overføring av kontroll og data
Programutførelse
Format og alternativer for å utføre funksjon 1
Tilleggsfunksjoner
Tekster utstedt under (innstilling, kontroll, utførelse) av programmet
Innholdsbeskrivelse

Konklusjoner om den generelle strukturen til brukerhåndboken i samsvar med GOST 19.xxx

Den generelle strukturen til brukerhåndboken i samsvar med GOST 19.xxx lider tydeligvis ikke, som IEEE Std 1063-2001, av mangelen på dekning. Overskudd gir som kjent opphav til kvalitet. Alt som programmet kan karakterisere er listet opp. Separate underseksjoner kan til og med virke overflødige, for eksempel underseksjonen "Programmeringsspråk som programmet er skrevet på".

Det ser ut til, hva bryr brukeren seg om på hvilket språk kildekoden til programmet ble skrevet? På den annen side, kanskje «... trenger noen dette? Dette betyr at det er nødvendig ... ". Når alt kommer til alt, når du kjøper en borgerlig TV, ønsker du å få et skjematisk diagram for den. Samsung og Sonya mislykkes også. Hva om funksjonsfeilen er ubetydelig og det ser ut til å være mulig å fikse det hjemme, uten en tur til et servicesenter?

På samme tid, for hele bredden av dekning, er det ingen eksplisitt:

• Programvareinstallasjon og de-installasjon, hvis utført av brukeren;
• Orientering til bruk av funksjonene til det grafiske brukergrensesnittet;
• Få tilgang til, eller logg på og signer av programvaren;
• Naviger gjennom programvaren for å få tilgang til og gå ut av funksjoner og mer.

Forfatteren klarte å spre noe i seksjonen Korrespondansetabell for GOST 19.xxx og IEEE Std 1063-2001, men det er alltid ikke nok tid til å "rynke tankene", brukermanualen skulle som alltid ha vært klar sist uke.

Forfatteren var for lat til å vise koblingene mellom delene av den generelle brukerhåndboken og delene, siden de angitte koblingene er åpenbare.

Konklusjoner fra kilder

Så hvis de tre første problemene generelt er løst, forblir det ekstreme problemet uløst.

Manifestforfatteren er mer tilbøyelig til å anbefale utvalg ord * og konstruksjonen av forslag, IEEE Std 1063-2001, i beste fall fører til krav til strukturen til brukerhåndboken, men gir ingen spesielle detaljer, i GOST 19.xxx prosedyrene for å fylle ut delene av håndboken er ikke foreskrevet. Kanskje organisere en slags blanding av fransk og Nizhny Novgorod? Bruke alle fire kildene som fire bestanddeler?

* I dag er det borgerlige på moten – det såkalte. kontrollert Språk ... Blant representantene for den "opplyste russiske intelligentsia" er den mest populære den russiske analogen i verbformen av imperativ stemning - filter basar !

En blanding av fransk med Nizhny Novgorod

Hvorfor ikke? Ta det beste av GOSTene til det 19. systemet, - en generalisert struktur i brukerhåndboken, legg til noen få forklarende fra IEEE Std 1063-2001 og fortynne den med uuttømmelig stilkultur og ressurser fra Kagarlitskys manifest? Gi blandingen et slankt, strengt utseende, form den neste med detaljerte kommentarer? Og hva skal jeg gjøre hvis ingen av de ovennevnte kildene og komponentene individuelt er i stand til å gi svar på alle spørsmålene som stilles?

Korrespondansetabell for GOST 19 og IEEE Std 1063-2001

GOST 19.xxx	IEEE Std 1063-2001
merknad
	Introduksjonen skal beskrive den tiltenkte målgruppen, omfanget og formålet for dokumentet og inneholde en kort oversikt over programvarens formål, funksjoner og driftsmiljø.
Formålet med dokumentet	formålet med dokumentet (introduksjon)
Sammendrag av hoveddelen av dokumentet	omfang (introduksjon)
Generell informasjon om programmet
Betegnelse og navn på programmet
Programmeringsspråk som programmet er skrevet på
Informasjon om formålet med programmet	kort oversikt over programvareformålet (introduksjon)
Informasjon tilstrekkelig til å forstå funksjonene til programmet og dets drift	det er ingen lignende underseksjon
Funksjoner i programmet
Klasser av oppgaver som skal løses
Beskrivelse av oppgaver
Metoder for problemløsning	Dokumentasjon skal relatere hver dokumentert funksjon til den overordnede prosessen eller oppgavene
Funksjoner som utføres av programmet	kort oversikt over programvaren ... funksjoner (introduksjon)
Beskrivelse av hovedkarakteristikkene og funksjonene til programmet	det er ingen lignende underseksjon
Tidskarakteristikker
Arbeidstid
Kontrollverktøy for korrekt utførelse og selvhelbredelse av programmet
Begrensninger i programmets omfang
Informasjon om funksjonell restriksjon
Bruksvilkår for programmet	Hvis ulike versjoner av programvaren er tilgjengelige for ulike driftsmiljøer, bør tittelsiden spesifisere gjeldende driftsmiljø(er), inkludert versjon(er) av maskinvare, kommunikasjon og operativsystem(er) (4.3. Innhold i identifikasjonsdata)
Betingelser som kreves for gjennomføring av programmet	det er ingen lignende underseksjon
Informasjon om maskinvaren og programvaren som sikrer gjennomføringen av programmet	Dokumentasjon for maskinvare- og programvaremiljøet (4.11 Informasjon om relaterte informasjonskilder)
Krav til tekniske midler	det er ingen lignende underseksjon
Enheter som brukes når du kjører programmet
RAM størrelse
Minimum og (eller) maksimal sammensetning av maskinvare og programvare
Krav til sammensetningen og parameterne til perifere enheter
Programvare som kreves for driften av programmet	kort oversikt over ... driftsmiljø (introduksjon)
Programvarekrav	det er ingen lignende underseksjon
Krav til andre programmer
Krav og betingelser av organisatorisk, teknisk og teknologisk art
Beskrivelse av den logiske strukturen
Algoritme for programmet	algoritmer (4.5 Konsept for operasjoner)
Metoder som brukes	bruke metoder som en visuell eller verbal oversikt over prosessen eller arbeidsflyten (4.5 Konsept for operasjoner)
Informasjon om strukturen i programmet	det er ingen lignende underseksjon
Informasjon om komponentene i programmet
Beskrivelse av funksjonene til komponentene
Informasjon om relasjonene mellom de inngående delene av programmet
Informasjon om koblinger til andre programmer
Inn- og utdatainformasjon
Generelle kjennetegn ved inngangs- og utdatainformasjon	det er ingen lignende underseksjon
Inndatadetaljer
Art, organisering og foreløpig utarbeidelse av inndata
Utdatadetaljer
Art og organisering av produksjonen
Format, beskrivelse og metode for koding av utdataene
Beskrivelse av informasjonskoding
Programinnstilling	Identifikasjon av tekniske eller administrative aktiviteter som må gjøres før du starter oppgaven (4.7 Informasjon for prosedyrer og veiledninger)
Beskrivelse av trinnene for å konfigurere programmet	det er ingen lignende underseksjon
Tilpasning til sammensetningen av tekniske midler
Funksjonsvalg
Illustrerende eksempler
Sjekker programmet
Beskrivelse av måter å sjekke funksjonaliteten til programmet	det er ingen lignende underseksjon
Testtilfeller	Eksempler skal illustrere bruken av kommandoer (4.8 Informasjon om programvarekommandoer)
Kjør metoder	det er ingen lignende underseksjon
resultater
Programutførelse
	Programvareinstallasjon og avinstallering, hvis utført av brukeren (4.6 Informasjon for generell bruk av programvaren)
Lansering av programmet	det er ingen lignende underseksjon
Inngangspunkter til programmet *	Få tilgang til, eller logg på og logg av programvaren (4.6 Informasjon for generell bruk av programvaren)
Metoder for overføring av kontroll- og dataparametere	det er ingen lignende underseksjon
Programutførelse
Beskrivelse av funksjonen som utføres 1	En kort oversikt over formålet med prosedyren og definisjoner eller forklaringer av nødvendige konsepter som ikke er inkludert andre steder (4.7 Informasjon for prosedyrer og veiledninger)
Format og mulige alternativer for kommandoer for å utføre funksjon 1	Navigering gjennom programvaren for å få tilgang til ... funksjoner (4.6 Informasjon for generell bruk av programvaren) Instruksjonstrinn skal presenteres i ytelsesrekkefølge (4.7 Informasjon for prosedyrer og veiledninger) Dokumentasjonen skal forklare hvordan man kan avbryte og angre operasjonen under utførelse av en kommando og hvordan man starter den på nytt, hvis mulig. Dokumentasjonen skal forklare formatene og prosedyrene for brukeroppgitte programvarekommandoer, inkludert nødvendige parametere, valgfrie parametere, standardalternativer, rekkefølge av kommandoer og syntaks (4.8 Informasjon om programvarekommandoer)
Programmer svar på kommandoer for å utføre funksjon 1	Dokumentasjonen skal beskrive hvordan man gjenkjenner at kommandoen er vellykket utført eller unormalt avsluttet (4.8 Informasjon om programvarekommandoer)
Slutt på programkjøring	Navigering gjennom programvaren ... for å gå ut av funksjoner Metoder for å avbryte, avbryte og starte operasjoner på nytt (4.6 Informasjon for generell bruk av programvaren)
Tilleggsfunksjoner
Beskrivelse av tilleggsfunksjonalitet til programmet	det er ingen lignende underseksjon
Beskrivelse av bruk av tilleggsfunksjonalitet til programmet
Programmeldinger	Relevante advarsler, advarsler og merknader som gjelder for hele prosedyren (4.7 Informasjon for prosedyrer og veiledninger)
Tekster til meldinger utstedt under (innstilling, kontroll, utførelse) av programmet	det er ingen lignende underseksjon
Innholdsbeskrivelse
Beskrivelse av handlinger som skal utføres på disse meldingene

Det er mange typer å gi hjelpeinformasjon til brukeren - disse er FAQ (ofte stilte spørsmål, ofte stilte spørsmål) og online hjelp og brukerveiledning (brukerveiledning) og populære tips (coachmarks, se eksempel nedenfor), treningsvideoer og andre.

Det er ulike grunner til at du trenger å skrive en systembrukerhåndbok. Fra og med kundens forespørsler (i min praksis var det et tilfelle da kunden måtte levere en brukermanual etter hver iterasjon, slik at han med dens hjelp kunne gjennomføre aksepttesting av iterasjonsfunksjonaliteten) og avsluttet med vilkårene i kontrakten angående levering av ferdig programvare, hvis vi snakker om programvareutvikling på bestilling. Ved utvikling av eget produkt er det også ofte det å skrive en brukermanual.

En analytiker blir ofte ansatt for å lage en guide hvis det ikke er mulig å tildele den til en teknisk skribent. I det overveldende flertallet av tilfellene er det analytikeren som har den mest komplette kunnskapen om systemet; han har også evnen til å uttrykke tankene sine tydelig skriftlig på grunn av profesjonens spesifikasjoner. Derfor har jeg måttet forholde meg til opprettelsen av brukermanualer mer enn én gang.

Nedenfor er noen fremgangsmåter for å skrive en god brukerveiledning. Noen av dem vil kanskje være nyttige for noen når de skal skrive kravspesifikasjoner.

1. Standarder

Det er ofte nødvendig å skrive et dokument som oppfyller kravene i gjeldende standarder. Det kan bli:

• IEEE Std 1063-2001, "IEEE Standard for Software User Documentation";
• GOST 19:
  • GOST 19.402-78 ESPD. Programbeskrivelse;
  • GOST 19.502-78 ESPD. Generell beskrivelse. Krav til innhold og design;
  • GOST 19.503-79 ESPD. Systemprogrammeringsveiledning. Krav til innhold og design;
  • GOST 19.504-79 ESPD. Programmeringsveiledning. Krav til innhold og design;
  • GOST 19.505-79 ESPD. Brukerhåndbok. Krav til innhold og design.

Hvis prosjektets behov lar deg ikke følge stive standarder, kan i alle fall studere disse dokumentene tjene som utgangspunkt for å skrive et kvalitetsdokument.

Yuri Kagarlitskys bok MetaGuide kan også være nyttig. Veiledning for utviklere av teknisk dokumentasjon for programvare.

2. Struktur

Tenk godt på strukturen til dokumentet: det skal dekke all funksjonaliteten til systemet, være komplett og forståelig.

En god bruksanvisning bør inneholde:

• Merknad, som gir et sammendrag av innholdet i dokumentet og dets formål. Det anbefales også å skrive en kort oppsummering i begynnelsen av hver hoveddel.
• Introduksjon som inneholder informasjon om hvordan du best bruker denne håndboken
• Innhold
• Kapitler beskriver hvordan bruk PÅ
• Ordliste og
• Emneindeks

Brukerhåndboken kan også inneholde:

• FAQ og svar på dem
• Lenker for ytterligere informasjon om systemet
• Kapittel beskriver mulig Problemer og måter å løse dem på

Alle kapitler og avsnitt, samt figurer og tabeller, er best nummerert slik at de kan refereres til i dette dokumentet eller fra et annet dokument.

3. Brukere

Tenk på typiske brukere av denne programvaren: det er nødvendig at dokumentet hjelper dem med å løse deres daglige oppgaver.

Det kan til og med være fornuftig å lage forskjellige seksjoner (eller til og med forskjellige dokumenter) for forskjellige brukergrupper, hvis deres interaksjon med systemet vil være radikalt forskjellig. For eksempel vil systemadministratorer (personer med ansvar for kontoer, tilgangsrettigheter osv.) være interessert i en helt annen funksjonalitet enn vanlige brukere.

Respekter brukerne av systemet, ikke skriv instruksjoner i en avvisende stil.

4. Funksjoner ved presentasjonen

Husk at talestilen eller forretningsbrevet er forskjellig fra den i teknisk dokumentasjon, og spesielt i brukermanualen.

Lederstil bør være nøytral-formell – bruken av stilfargede ord distraherer brukeren fra poenget.

Gode ​​grammatikkkunnskaper og litt psykologi vil komme godt med for å skrive et godt dokument.

4.1 Skriv kort og logisk. Ikke oppgi unødvendige detaljer, ikke dupliser informasjon. Rekkefølgen der informasjonen er nevnt i brukerhåndboken må samsvare med rekkefølgen av brukerhandlinger:

God: Velg i Fil-menyen Lagrepunkt.
Verre: Plukke ut Lagre element fra Fil-menyen.

4.2 Bruk imperativet, ikke bruk høflige fraser (vær så snill, kunne osv.) - overdreven høflighet vil være en hindring her.

God: Klikk Logg ut.

Verre: Det er nødvendig å klikke Logg ut for å logge ut gjeldende brukerkonto fra systemet .

Verre: Hvis brukeren ønsker å logge ut gjeldende brukerkonto fra systemet(e) må han klikke Logg ut.

4.3 Strukturer informasjonen. Du kan ofte finne råd for å prøve å unngå lister, men trinn-for-trinn-informasjon blir alltid bedre oppfattet.

God:
Tilskapeprosjekt:

1. Klikk på Skape knappen på verktøylinjen.
2. På Skape Prosjekt overlegg fyll ut alle obligatoriske felt.
3. Klikk på Lagreknapp for å redde prosjektet.

Verre: For å opprette et prosjekt klikk på Skape knappen på verktøylinjen, på Opprett prosjekt overlegg fyll ut alle obligatoriske felt, klikk på Lagre knappen for å lagre prosjektet.

4.4 Ikke bruk fremtid eller preteritum... For eksempel finnes ofte manualer der systemets respons på brukerhandlinger formidles i fraser formulert i fremtidsform. Programvare har ingen fortid eller fremtid: alt skjer i nåtiden som et direkte resultat av en spesifikk brukerhandling. Så snart en hendelse inntreffer, reagerer programvaren.

God: Når brukeren klikker på Start knappen, programmet starter prosessen.

Verre: Når brukeren klikker på Start knappen, programmet vil starte prosessen.

4.5 Sjekk betydningen av ord. Hvis du skal skrive et dokument på et fremmedspråk, bør du i størst mulig grad forsøke å unngå feil knyttet til utilstrekkelig kunnskap i språket.

For eksempel betyr verbet "trykk" å trykke på en tast på tastaturet, og "klikk" betyr å trykke på en knapp eller et ikon i programvinduet med musen, og "treff" er generelt et slangord.

Selvfølgelig er stavefeil uakseptable.

4.6 Ikke bruk synonymer for samme begrep. I IT-litteraturen på engelsk (eller et hvilket som helst annet) språk er det et standardsett med verb som angir handlinger (klikk, dobbeltklikk, velg, skriv, trykk osv.) og det samme standardsettet med kontrollnavn. Bestem deg for terminologi og hold deg til den gjennom hele dokumentet.

Tillat for eksempel ikke at en rullegardinmeny blir navngitt rullegardin i én del av dokumentet og en kombinasjonsboks eller rullegardinliste i en annen. Dette forvirrer brukeren.

4.7 Bruk forkortelser med omhu og eliminer sjargong.

Det antas at forkortelser ikke skal brukes, men hvis en lang term brukes flere ganger, er det nødvendig å skrive hele navnet ved den første omtalen i teksten og ved siden av det - forkortelsen i parentes, og videre i teksten. tekst kan du bare bruke forkortelsen. Hvis dokumentet inneholder en ordliste eller et avsnitt med forkortelser, skal de transkriberes der.

Ikke bruk slangord, metaforer og termer som er lånt fra et annet språk enn språket i manualen.

5. Utseende

5.1 Tenk på stilen til dokumentet... Dette kan være en bedriftsmal eller programvarefargeskjema, eller et design laget spesielt for et dokument.

Når du skriver, fremhev gjerne viktige ting med stiler eller farger (for eksempel fete knappenavn). Det er imidlertid viktig å forstå at feil valgte fonter og farger kan gjøre det vanskelig å oppfatte innholdet i dokumentet.

5.2 Ikke spar plass- del teksten i korte avsnitt, bruk relativt store overskrifter, start en ny seksjon på en ny side. Dette vil lette oppfatningen av informasjonen som leses av brukeren.

5.3 Bruk piktogrammer og illustrasjoner... Det er en oppfatning at du ikke bør la deg rive med av illustrasjoner, og også inkludere ikoner i teksten i brukermanualen. Imidlertid er grafisk informasjon alltid bedre oppfattet og husket, så skjermbilder og nødvendige ikoner bør være til stede i en god manual i tilstrekkelig, men rimelig antall.

6. Støtte

Ikke gå glipp av det faktum at programvare endres over tid, noe som betyr at dokumentet ditt også må endres for å forbli relevant.

Konklusjon

Vær oppmerksom på at irritasjon fra et dokument av dårlig kvalitet kan projiseres av brukeren på programvaren og dermed påvirke beslutningen om å bruke produktet.

Husk det viktigste: dokumentet skal hjelpe brukerne.

Artikkelen er utarbeidet av

Tarasyuk Nadezhda, medlem av fellesskapet,

analytiker med 6 års erfaring innen feltet.

@ Zhuravlev Denis

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

Som regel oppstår behovet for dokumentasjon i samsvar med GOST i samarbeid med offentlige organisasjoner, store industrier og selskaper, med tilpasset programvareutvikling for anbud og offentlige bestillinger, eller, om nødvendig, legg til et programvareprodukt i "Unified Register of Russian Programmer for elektroniske datamaskiner og databaser (register over innenlandsk programvare) ".

Det er to serier (sett) med standarder som regulerer settet med dokumenter som opprettes og reglene for utformingen av dem i utviklingen av automatiserte systemer, komplekser og programvare:

• GOST 34 - Automatiserte systemer
• GOST 19 - Unified system of program documentation (ESPD)

På den ene siden konkurrerer disse to standardene med hverandre, jeg tilbyr ulike alternativer for 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 til dokumentene som er opprettet.
GOST 19 bestemmer i stor grad reglene for papirarbeid.
Derfor, i praksis, brukes begge disse GOST-ene ofte samtidig.

Hvis vi snakker spesifikt om dokumentasjonen 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 Guide", men for programvare er det det første alternativet som oftere brukes.

Brukermanualen følger med ethvert produkt, program, system. Den skal gi brukeren informasjon om produktets egenskaper, dets funksjonalitet, hvordan man bruker og arbeider med det.

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

Ikke bare er det nødvendig å studere et stort antall normative dokumenter fylt med kryssreferanser og skrevet på et komplekst, unødvendig geistlig, nærmest juridisk språk, men det er også nødvendig å velge derfra kravene spesifikt knyttet til typen dokument som skal brukes. opprettet. Deretter, gjennom hele arbeidet, må du hele tiden overvåke overholdelse av disse kravene i arbeidsdokumentet, og kontinuerlig sjekke mot standardene.

Vanligvis forverres problemet av mangel på tid, siden det dessverre ofte er vanlig å skrive brukerdokumentasjon helt på slutten av et prosjekt, rett før fristen - datoen for levering eller lansering av systemet.

For en erfaren teknisk skribent er GOST-dokumentasjon kanskje ikke så vanskelig. Men selv for ham kan utarbeidelsen av maler for nye dokumenter, bringe eksisterende dokumentasjon til standardene eller sjekke det endelige dokumentet for samsvar med disse kravene, ta betydelig tid.

Dr.Explain forenkler opprettelsen av en GOST-brukermanual

Fra og med versjon 5.5.1100 tilbyr programmet for å lage brukerdokumentasjon Dr.Explain funksjonen for automatisert støtte for GOST 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øtten til følgende standardkrav:

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

Administrasjon av GOST-støttefunksjonen for et prosjekt er tilgjengelig i Prosjektinnstillinger i seksjonen Generell.

Når GOST-støttemodus er aktivert for prosjektet, blir de tilsvarende brukerinnstillingene for de utskrivbare RTF \ DOC- og PDF-formatene automatisk overstyrt av programmet, noe som sikrer at parametrene til utdatadokumentene fullt ut samsvarer med standardkravene.

Egendefinerte innstillinger vil bli brukt for HTML- og CHM-utdataformater uavhengig av om GOST-støttemodus er aktiv. Dette fjerner begrensningen på gratis styling av disse formatene og tillater for eksempel å gi online hjelp helt i en bedrifts- eller tematisk stil.

Viktig:

Viktig: GOST-støttefunksjonen er kun tilgjengelig i Dr.Explain i den russiskspråklige versjonen av grensesnittet. Språket til programgrensesnittet velges i menyen Innstillinger \ Programspråkvalg (Alternativer \ Applikasjonsspråk).

Oppretting av en ny brukerhåndbok i samsvar med GOST

For å lage en ny brukermanual for kravene til GOST 34 i Dr.Explain-programmet, kan du bruke menykommandoene Fil \ Opprett lokalt prosjekt - GOST 34 brukerveiledning eller Fil \ Opprett et delt prosjekt på tiwri.com - Brukerhåndbok i samsvar med GOST 34

eller lignende knapper på startskjermen til applikasjonen.

Programmet vil opprette et nytt prosjekt, som allerede inneholder tittelsidemalen, merknaden, innholdsfortegnelsen og obligatoriske seksjoner designet i samsvar med GOST.

I teksten til hver del vil det være et kort hint om hva som skal inkluderes i denne delen. Brukeren trenger kun å fylle seksjonene med relevant innhold.

Layoutinnstillingene for de utskrivbare formatene RTF / DOC og PDF vil bli satt i samsvar med kravene i GOST 19.

Ta med eksisterende brukerdokumentasjon i samsvar med kravene til GOST

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

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 den originale dokumentasjonen ennå ikke er lagret i Dr.Explain, men er lagret i andre formater, er det første trinnet å importere de eksisterende dokumentene inn i programmet. Dr.Explain støtter import av dokumenter fra en rekke populære formater. Importkommandoer er tilgjengelige både i startvinduet til programmet og i menyen Fil.

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

Brukeren må overføre innholdet i disse seksjonene eller seksjonene helt ved å dra-n-slipp til hovedprosjekttreet og redigere dem etter behov.

Som i det første tilfellet vil layoutinnstillingene for de utskrivbare formatene RTF / DOC og PDF bli satt i samsvar med kravene i GOST 19.