Noderīgi padomi

Tehniskā dokumentācija

Pin
Send
Share
Send
Send


Programmatūras dokumentācijas izveidošana ir viena no visvairāk pieprasītajām tehnisko rakstnieku darbības jomām. Tātad, lai kļūtu par neaizstājamu (un mūsu darbības jomā neaizvietojams notikums) speciālistu, jums jāapgūst šī joma.

Laba programmatūras dokumentācija neatkarīgi no tā, vai tā ir specifikācija programmētājiem un testētājiem, tehnisks dokuments iekšējiem lietotājiem vai programmatūras rokasgrāmata un palīdzības faili galalietotājiem, palīdz personai, kas strādā ar programmatūru, izprast tās funkcijas un funkcijas. Laba programmatūras dokumentācija ir specifiska, kodolīga, aktuāla un sniedz visu informāciju, kas nepieciešama personai, kura lieto programmatūru. Zemāk ir norādījumi, kā uzrakstīt programmatūras dokumentāciju tehniķiem un lietotājiem.

1. un 2. metode: dokumentācijas rakstīšana tehniķiem

  1. Izlemiet, kādu informāciju iekļaut.. Programmatūras specifikācijas kalpo kā ceļveži interfeisa izstrādātājiem, programmētājiem, kas raksta kodu, un testētājiem, kuri pārliecinās, ka programma darbojas kā plānots. Precīza informācija ir atkarīga no programmas, taču tā var ietvert šādus elementus:
  • Galvenie lietojumprogrammu faili. Tajos var ietilpt faili, ko izveidojusi izstrādes komanda, datu bāzes, kurām piekļūst programmas izpildes laikā, un trešo pušu utilītas.
  • Funkcijas un kārtība. Tajos ietilpst katras funkcijas vai apakšprogrammas paskaidrojums, ieskaitot ievades un izvades vērtību diapazonu.
  • Programmas mainīgie un konstantes un to izmantošana lietojumā.
  • Programmas kopējā struktūra. Lietojumprogrammas diska versijā tas var būt programmas atsevišķo moduļu un bibliotēku apraksts. Tīmekļa lietojumprogrammai - norāde uz to, kuras lapas saista ar kādiem failiem.
  1. Izlemiet, cik daudz dokumentācijas jums jāiekļauj programmas kodā, un cik lielai no tās jābūt atsevišķi.. Jo vairāk tehniskās dokumentācijas tiek izstrādāta programmas avota kodā, jo vieglāk to atjaunināt un uzturēt kopā ar kodu, kā arī dokumentēt dažādas oriģinālās lietojumprogrammas versijas. Vismaz dokumentācijā avota kodā jāpaskaidro funkciju mērķis, kārtība, mainīgie un konstantes.
  • Ja avota kods ir īpaši garš, to var dokumentēt kā palīdzības failu, kurā varat indeksēt vai palaist atslēgvārdu meklēšanu. Tas ir īpaši ērti lietojumprogrammām, kurās programmas loģika ir sadalīta vairākās lapās un ietver vairākus papildu failus, piemēram, noteiktas tīmekļa lietojumprogrammas.
  • Dažām programmēšanas valodām, piemēram, Java un .NET Framework (VisualBasic .NET, C #), ir savi standarti koda dokumentēšanai. Šajos gadījumos ievērojiet standartus, attiecībā uz kuriem dokumentācijas daļa jāiekļauj avota kodā.
  1. Izvēlieties atbilstošo dokumentācijas rīku. Zināmā mērā tas ir saistīts ar valodu, kurā kods tiek uzrakstīts, vai tas būtu C ++, C #, Visual Basic, Java vai PHP, jo šīm un citām valodām ir īpaši rīki. Citos gadījumos izmantojamais rīks ir atkarīgs no nepieciešamo dokumentu veida.
  • Lai izveidotu atsevišķus teksta dokumentācijas failus, pietiek ar Microsoft Word teksta redaktoriem, ja dokumentācija ir diezgan īsa un vienkārša. Gariem un sarežģītiem teksta failiem daudzi tehniskie rakstnieki dod priekšroku īpašam dokumentācijas rīkam, piemēram, Adobe FrameMaker.
  • Palīdzības failus avota koda dokumentēšanai var izveidot ar jebkuru palīdzības rakstīšanas rīku: RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare vai HelpLogix.

Kā uzrakstīt tehnisko dokumentāciju?

Kā uzrakstīt tehnisko dokumentāciju? Vai tā saturs ir teksts? Gan tehniskās dokumentācijas teksti kopumā, gan arī kādas tehniskas publikācijas, sākot no žurnālu rakstiem un beidzot ar doktora disertācijām? Vienkāršas un efektīvas metodes, kas ļauj rakstīt saprotamus tekstus, neizmantojot nekādas buržuāziskas apraksta tehnoloģijas, lasāmas un acīmredzami iztur gan visstingrāko un pamatotāko kritiku, gan arī nekaunīgos, nepamatotos un tehniski nepamatotos pretinieku izteikumus. 2018. gada 06. gada pārskatīšana.

Kā vispār uzrakstīt "caurspīdīgu" un saprotamu tehniskās dokumentācijas tekstu?

Teksta galvenā ideja “vispār” ir attēlota attēlā. Tagad, kā saka militārpersonas, visu, kas tika pateikts, mēs izskaidrosim ar vārdiem: ir vēlams, lai teksts būtu strukturēts, nevis plāns, kas dominē klasiskajā krievu literatūrā. Ar “plakanu” mēs domājam plakanu tekstu (no lat. Planus plakana, pat).

Atcerieties Paustovska puslapu rindkopas, kas pilnībā sastāv no sarežģītiem teikumiem un saliktiem teikumiem, vai Tolstoja franču tekstu piecu lappušu tekstā, kam seko piecu lappušu tulkojums zemsvītras piezīmēs. Ikviens, kurš ir spējis lasīt Karu un mieru no vāka līdz vākam, mūža laikā ir pieminekļa vērts. Uzstādīts blakus paša Ļeva Nikolajeviča piemineklim.

Tagad par saprotamību. Izpratne ir programmatūras rīka īpašību kopums, kas raksturo izmaksas, kas saistītas ar lietotāja centieniem izprast šī programmatūras rīka loģisko koncepciju. Piezīme - loģiskā koncepcija nozīmē pamatjēdzienus, principus un vienošanās, kas noteikumu sistēmai darbam ar programmatūru nodrošina konsekventu un saprātīgu raksturu un ļauj jums loģiski precīzi noteikt šo noteikumu konkrēto mērķi un saturu [no lietotnes 3.1. 2 GOST 28806-90].

Programmatūras rīks ir programmas un tai pievienotās dokumentācijas kombinācija, tāpēc programmas saprotamība ir diezgan piemērojama gan programmas dokumentācijai, gan tehniskajai dokumentācijai kopumā.

Par izpratni par vadību. Šī grāmata ir par lietotāja rokasgrāmatu, un jebkura rokasgrāmata ir instrukciju kopums, un tās uzdevums ir sniegt (un nenododtā kā mūsu pašmāju politiskā un televīzijas “beau monde” tagad pauž viedokli) soli pa solim, kā sasniegt vienu vēlamo rezultātu, ir gan pionieris, gan pensionārs. Norādītā metode tekstu parādīšanai “kopumā” ir ļoti piemērojama mūsu gadījumā. Un vispār lietotājam nav jāsaprot nekādas loģiskas vadības koncepcijas.

Kā uzrakstīt strukturētu tekstu?

Lai "uzlabotu iespaidu", tekstu vislabāk izkārtot strukturētā hierarhiskā formā, lai viss būtu "izlikts plauktos", kā parādīts attēlā. Teksts kļūst daudz caurspīdīgāks un saprotamāks, kā arī iegūst "drošu aizsardzību".

Dzīvē notiek daudz interesantu lietu. Ļoti bieži nākas atvairīt sabiedrību, cenšoties sevi pierādīt uz citu rēķina no sava veida troļļiem, ne tikai no tīkla, bet arī no dzīviem un reāliem. Šo nepatīkamo cilvēku viltības saistībā ar labi strukturētu tekstu nepaiet garām

Iedomājieties, ka pretinieks izlikās par muļķi un paziņo, ka viņš nesaprot, kam paredzēti AutorIT mainīgie. Ir ļoti viegli tikt galā ar šādu pretinieku, ja, protams, viņš var lasīt (vismaz noliktavās):

  1. Pirmais jautājums: “Kas rakstīts ievadfrāzē?” Atbilde: “Paredzēti AutorIT mainīgie:”,
  2. Otrais jautājums: “Kas ir ierakstīts saraksta pirmajā rindkopā?” Atbilde: “. teksta, grafisko elementu utt. fragmentu glabāšanai ",
  3. Trešais jautājums: “Kādam nolūkam ir AuthorIT mainīgie? Izlasiet ievadteikumu un saraksta pirmo daļu vienā teikumā ",
  4. .
  5. Un pēdējais jautājums (nonāvējošais trieciens): “KAS NEBIJA PAREDZĒTS ?!”

Tādējādi strukturētais teksts kļūst caurspīdīgs, aizsargāts un, ja vēlaties, piespiedu kārtā saprotams. Pretiniekam vienkārši nav, par ko strīdēties, viņš ir stūrēts un sēž (kā to precīzi izteicis Lukašenko kungs) kā pele zem slotas.

Par GOST autentisko tekstu un citu normatīvo dokumentu ieviešanas tehniskajā dokumentācijā priekšrocībām

Autentisku valsts standarta specifikāciju tekstu un citu normatīvo dokumentu ieviešana tehniskajā dokumentācijā ir brīnišķīgs veids, kā likt pretiniekam uz ceļgaliem, tikai pretinieks šajā gadījumā šķiet nevis muļķīgs impulsīvs trollis no sērijas “radošs - miskaste, autors - kaza”, bet gan biedrs, kurš iedomājas sevi kā ekspertu attiecīgajā jomā.

Droši vien izskaidrojiet doto grāmatas fragmentu ar vārdiem un nevajag. Labāk ir pastāstīt kādu interesantu gadījumu no dzīves.

Reiz, aukstajā ziemas sezonā - un salnu bija apmēram trīsdesmit - tika saņemts pasūtījums izstrādāt programmu un metodiku gāzes plūsmas mērīšanas aprīkojuma testēšanai un gāzes kvalitātes kontrolei. Turklāt pasūtījumu nāca no pašiem gāzes darbiniekiem.

Sākumā tika nolemts atteikties, bet viņi patiešām jautāja. Burtiski dzīvības un nāves jautājums. Kāpēc nedarboties, ja tas tā ir? Pieredze dažādu veidu testu veikšanā ar “Tehnisko dokumentāciju” ir vairāk nekā pietiekama.

Mēs to paņēmām, cietām apmēram divas nedēļas, savācām informāciju, konsultējāmies, atradām reglamentējošos dokumentus attiecīgajā jomā - viņi tika galā ar uzdevumu. Un šeit klienti, kuri paši neuzdrošinājās veikt šo darbu, jutās kā "eksperti".

Faktiski "pārbaude" ilga ne vairāk kā desmit minūtes. Pēc aculiecinieka (aculiecinieku) teiktā: ". tas (eksperts) sit histērijā un kliedz, ka ir zinātņu kandidāts, un šis (izstrādātājs) pieklājīgi smaida un ar pirkstu pieliek zemsvītras piezīmēs ar GOST terminu definīcijām un izmantoto standartu sarakstu. "

Apkārtējiem cilvēkiem bija jautri. Ņemiet vērā, ka tā paša klienta interesēs vēlāk tika izstrādāts vēl viens PM, tikai sarežģītāki mehāniskie testi, taču kāda iemesla dēļ nevienam vairs nebija idejas veikt tā pārbaudi.

PAREIZI RAKSTIET TEHNISKO DOKUMENTĀCIJU - un, iespējams, pamodīsit visus

DR. PASKAIDROJIET

Frontend izstrādei zināmā mērā ir nepieciešama arī dokumentācija. DR palīdzēs izveidot dokumentāciju gan regulārām, gan tiešsaistes lietojumprogrammām, kas rakstītas jebkurā programmēšanas valodā, jebkurā attīstības vidē, izmantojot jebkuru ietvaru. PASKAIDROJIET. Tas filtrē saskarnes galvenos elementus un pēc tam iegūst ar to saistītos meta datus. Pēc tam jūs varat mainīt saņemto informāciju, lai ātri izveidotu interfeisa dokumentāciju.

LaTex ir de facto standarts zinātnisko projektu dokumentēšanai. Tomēr to var izmantot arī cita veida projektiem, ieskaitot kodu un projekta dokumentāciju. Sagatavojot dokumentu, autors norāda teksta loģisko struktūru (sadalot to tekstā) nodaļas, sadaļas, galdi, attēlus) un ļauj LaTeX rūpēties par tā attēlošanu.

Markdown, Jāņa Grūbera radīšana, ļoti vienkārša un eleganta teksta iezīmēšanas sintaksekas palīdzēs uzrakstīt kvalitātes kodu un dokumentāciju. No tehniskā viedokļa Markdown ir rīks teksta pārvēršanai HTML HTML rakstītājiem, taču to var izmantot arī dokumentēšanai. Kā izstrādātājs jūs varat rakstīt dokumentāciju Markdown sistēmā un pēc tam izmantot Pandoc, lai pārveidotu to uz visu nepieciešamo formātu.

GhostDoc ir Visual Studio paplašinājums, ar kuru jūs varat viegli ģenerēt XML dokumentu komentārus. Rīks ģenerē komentārus, pamatojoties uz vairākiem faktoriem, ieskaitot vārdu, parametrus, kontekstuālo informāciju, tipus utt.

DABAS DOKS

Natural Docs ir vēl viens atvērtā koda rīks, kas darbojas ar daudzām programmēšanas valodām. Tas palīdzēs jums automatizēt koda dokumentācijas ģenerēšanu un pārveidot to HTML formātā. Pašlaik NATURAL DOCS atbalsta 19 programmēšanas valodas, tai skaitā Python, C ++, PL / SQL, Actionscript u.c.

PHPDOKUMENTS

Ja esat PHP izstrādātājs un vēlaties ģenerēt koda dokumentāciju no avota koda, jums jāapsver PhpDocumentor. Sistēmas pamatā ir PHP koda loģiskās struktūras (klases, funkcijas, mainīgie, konstantes) parsēšana un saskaņā ar noteiktiem standartiem uzrakstītu komentāru sasaiste ar to. Šis rīks var arī palīdzēt jums izveidot pārskatus un diagrammas un uzlabot vispārējo koda kvalitāti.

Kā straumēšanas platforma var palīdzēt koda dokumentēšanā? Varat straumēt vai saglabāt projekta darbu tieši Livecoding. Jums būs iespēja savas komandas locekļiem viegli atvērt piekļuvi svarīgām projekta sadaļām. Vairākas video izmantošanas kā koda dokumentēšanas priekšrocības. Daži no tiem ir uzskaitīti zemāk:

  • Šeit nav rakstīts, bet ir labāka konteksta izpratne.
  • Veiklas komandas var viegli izsekot projekta izmaiņām.
  • Tehniskie autori var izmantot video dokumentāciju, lai labāk izprastu projektu.
  • Izstrādātāji var ieguldīto laiku ietaupīt citu projekta iespēju ieviešanā.

Damians Volfs šo tēmu sīkāk aplūko rakstā “Kāpēc izstrādātāji raksta briesmīgu dokumentāciju un kā to atrisināt”.

Šodien mēs esam iepazinušies ar 10 rīkiem, lai vienkāršotu koda dokumentēšanu. Jāatzīmē, ka iepriekš minētie rīki darbojas kā papildinājumi dokumentācijas procesā.

Noskatieties video: Energoefektivitātes paaugstināšanas process. Tehniskā dokumentācija un tehniskie risinājumi. (Maijs 2020).

Pin
Send
Share
Send
Send