Dokumentacioni për softin është thjesht një grup artikujsh. Por edhe ata mund të të shqetësojnë. Fillimisht kërkon gjatë për udhëzimin e duhur. Pastaj përpiqesh të kuptosh tekstin e paqartë. Bën ashtu siç është shkruar, por problemi nuk zgjidhet. Kërkon një artikull tjetër, nervozohesh... Pas një ore heq dorë dhe largohesh. Kështu funksionon dokumentacioni i keq. Çfarë e bën atë të tillë, dhe si mund ta rregullosh — lexoni më poshtë.
Në dokumentacionin tonë të vjetër kishte shumë disavantazhe. Tani e gati një vit po e riparojmë atë, në mënyrë që skenari i përshkruar më sipër të mos prekte klientët tanë. Shikoni, dhe .
Problemi 1. Artikuj të paqartë, të shkruar keq
Nëse nuk mund të kuptosh dokumentacionin, çfarë kuptimi ka? Por askush nuk shkruan artikuj të paqartë me të keq. Ato e fitojnë këtë status kur autori nuk mendon për audiencën dhe qëllimin, derdh ujë dhe nuk e kontrollon tekstin për gabime.
- Audienca. Para se të shkruash një artikull, duhet të mendosh për nivelin e përgatitjes së lexuesit. Është logjike që në një artikull për fillestarët, nuk duhet të lihet pa përmendur hapat bazikë dhe të lini terma teknikë pa shpjegim, ndërsa në një artikull për një karakteristikë të rrallë, të nevojshme vetëm për profesionistët, duhet të shpjegosh kuptimin e fjalës PHP.
- Qëllimi. Gjithashtu, një gjë tjetër për të cilën është më mirë të mendosh përpara është që autori duhet të vendosë një qëllim të qartë, të përcaktojë veprimin e dobishëm të artikullit, dhe të vendosë se çfarë do të bëjë lexuesi pas leximin. Nëse nuk bëhet kjo, do të rezultojë një përshkrim përshkrimi.
- Uji dhe gabimet. Informacioni i tepërt dhe burokracitë, gabimet dhe shtypjet e gabuara e pengojnë perceptimin. Edhe nëse lexuesi nuk është një grammer-nazi, neglizhenca në tekst mund ta shqetësojë atë.
Konsideroni këshillat e mësipërme dhe artikujt do të bëhen më të qartë — e garantuar. Për ta bërë edhe më mirë, merrni parasysh pyetjet tona .
Problemi 2. Artikujt nuk përgjigjen të gjitha pyetjeve
Është keq kur dokumentacioni nuk ndjek zhvillimin, nuk përgjigjet ndaj pyetjeve reale, gabimet në të nuk korrigjohen për vite. Këto janë probleme më shumë të autorit, sesa të organizimit të proceseve brenda kompanisë.
Dokumentacioni nuk ndjek zhvillimin
Funkcioni është tashmë në lansim, marketingu planifikon ta përmendë atë, dhe këtu del se nuk ka ende artikuj të rinj ose përkthimesh në dokumentacion. Për shkak të kësaj, na ka ndodhur të shtyjmë lansimin. Mund të kërkojmë pafundësisht nga të gjithë që të transmetojnë detyrat në kohë te shkrimtarët teknikë, por kjo nuk do të funksionojë. Nëse procesi nuk automatizohet, situata do të përsëritet.
Ne kemi bërë ndryshime në YouTrack. Detyra për të shkruar një artikull mbi funksionin e ri i bie shkrimtarit teknik në të njëjtin moment kur mundësitë fillojnë të testohen. Atyherë, marketingu bën të ditur për të, që të përgatitet për promovim. Njoftimet arrijnë gjithashtu në mesazherin korporativ Mattermost, kështu që është e pamundur të humbasësh lajme nga zhvilluesit.
Dokumentacioni nuk pasqyron kërkesat e përdoruesve
Ne jemi mësuar të punojmë kështu: funksioni doli, ne treguam për të. E përshkruam si të aktivizohet, të çaktivizohet, dhe si të bëhen rregullime të imta. Por çfarë ndodh nëse klienti përdor softuerin tonë ndryshe nga sa ne e kishim parashikuar? Ose ka gabime për të cilat ne nuk kemi menduar?
Për të siguruar që dokumentacioni të jetë sa më i plotë, këshillojmë të analizoni ankesat në suport, pyetjet në forume të tematikës, kërkesat në motorët e kërkimit. Temat më të popullarizuara t'i dërgoni shkrimtarëve teknikë, që ata të plotësojnë artikujt ekzistues ose të shkruajnë të rinj.
Dokumentacioni nuk përmirësohet
Është e vështirë të bësh gjithçka perfekte nga fillimi, gabime do të ketë përherë. Mund të shpresojmë në reagime nga klientët, por pak i ndihmojnë ata që të raportojnë për çdo gabim shtypi, pasaktësi, artikuj të paqartë ose të paqënë. Përveç klientëve, dokumentacionin e lexojnë edhe punonjësit, kështu që ata shohin të njëjtat gabime. Kjo mund të përdoret! Duhet thjesht të krijoni kushte ku do të jetë e lehtë të raportosh për një problem.
Ne kemi një grup në portalin e brendshëm, ku punonjësit lënë vërejtje, sugjerime dhe ide për dokumentacionin. Sapo mbështetjes i nevojitet një artikull dhe ai nuk ekziston? Një testues vuri re një pasaktësi? Një partner u ankuar menaxherëve të zhvillimit për gabime? Gjithçka shkon në këtë grup! Shkrimtarët teknikë korrigjojnë disa gjëra menjëherë, disa i transferojnë në YouTrack, disa i marrin për t'u menduar. Që tema të mos shuhet, herë pas here ne i kujtojmë ekzistencën e grupit dhe rëndësinë e reagimeve.
Problemi 3. Artikulli i nevojshëm është i vështirë për t'u gjetur
Një artikull që nuk mund të gjendet, nuk është më i mirë se një artikull që nuk ekziston. Motoja e dokumentacionit të mirë duhet të jetë fraza "Lehtë për t'u kërkuar, lehtë për t'u gjetur". Si mund ta arrijmë këtë?
Organizoni strukturën dhe përcaktoni parimin e zgjedhjes së temave. Struktura duhet të jetë sa më e qartë, që lexuesi të mos pyetet "Ku mund ta gjej këtë artikull?". Nëse e përmbledhim, ekzistojnë dy qasje: nga ndërfaqja dhe nga detyrat.
- Nga ndërfaqja. Përmbajtja përputhet me seksionet e panelit. Kështu ka qenë në dokumentacionin e vjetër të ISPsystem.
- Nga detyrat. Titujt e artikujve dhe seksioneve reflektojnë detyrat e përdoruesve; në tituj pothuajse gjithmonë ka folje dhe përgjigje ndaj pyetjes "si të bësh". Tani po kalojmë në një format të tillë.
Pavarësisht se cila qasje zgjidhni, sigurohuni që tema përputhet me kërkesat e përdoruesve dhe është trajtuar në mënyrën që përdoruesi të zgjidhë saktësisht pyetjen e tij.
Të vendosni një kërkim të centralizuar. Në një botë ideale, kërkimi duhet të funksionojë, edhe kur bëni një gabim në shkronja ose në gjuhë. Kërkimi ynë në Confluence ende nuk mund të ofrojë këtë. Nëse keni shumë produkte, dhe dokumentacioni është i përbashkët, përshtatni kërkimin sipas faqes ku ndodhet përdoruesi. Në rastin tonë, kërkimi në krye punon për të gjitha produktet, dhe nëse jeni tashmë në një seksion të caktuar, atëherë vetëm për artikujt në të.
Shtoni përmbajtje dhe "bukë me krimba". Është mirë kur në çdo faqe ka një menu dhe bukë me krimba — rruga e përdoruesit deri në faqen aktuale me mundësinë për të rikthyer në çdo nivel. Në dokumentacionin e vjetër të ISPsystem, duhej të dilje nga artikulli për të hyrë në përmbajtje. Ishte e pakëndshme, prandaj në të reja e kemi korrigjuar këtë.
Vendosni lidhje në produkt. Nëse njerëzit vazhdojnë të vijë në mbështetje me të njëjtin pyetje, është e arsyeshme të shtoni një sugjerim me zgjidhjen e tij në ndërfaqe. Nëse keni të dhëna ose kuptim, për momentin kur përdoruesi përballet me problemin, mund të njoftoni gjithashtu me një newsletter. Do t'i tregoni kujdes dhe do të lehtësoni ngarkesën nga mbështetja.
Në anën e djathtë në dritaren e ngjitur, lidhja për artikullin mbi konfigurimin e DNSSEC në seksionin e menaxhimit të domain-eve ISPmanager
Konfiguroni lidhje kry crosses brenda dokumentacionitArtikujt që janë të lidhur mes tyre duhet të jenë "të lidhur". Nëse artikujt përbëjnë një seri, sigurohuni që të shtoni në fund të çdo teksti shigjeta përpara dhe prapa.
Me siguri, një person fillimisht do të shkojë të kërkojë përgjigjen për pyetjen e tij, jo te ju, por në motorin e kërkimit. Është e mërzitshme nëse nuk ka lidhje me dokumentacionin për shkak të arsyeve teknike. Pra, kujdesuni për optimizimin e motorëve të kërkimit.
Problemi 4. Dizajni i vjetër pengon perceptimin
Përveç teksteve të këqija, dizajni mund të prishë dokumentacionin. Njerëzit janë mësuar të lexojnë materiale të hartuara mirë. Bloget, rrjetet sociale, median - gjithë përmbajtja paraqitet jo vetëm bukur, por edhe në mënyrë të lehtë për lexim, e këndshme për sy. Prandaj, është e lehtë të kuptohet dhimbja e atij që sheh tekstin si në screenshotin më poshtë.
Në këtë artikull janë kaq shumë screenshot-e dhe theksime saqë ato nuk ndihmojnë, por vetëm pengojnë perceptimin (imazhi është i klikueshëm)
Nuk është e nevojshme të bëni nga dokumentacioni një lëndë të gjatë me shumë efekte, por rregullat bazike duhet të merren parasysh.
DizajniPërcaktoni gjerësi e tekstit kryesor, fontin, madhësinë, titujt dhe hapësirat. Angazhoni një dizajner, dhe për të pranuar punën ose për t'u përballur vetë, lexoni librin e Artem Gorbunov "Tipografia dhe dizajni". Në të paraqitet vetëm një nga pikëpamjet për dizajnin, por kjo është mjaft e mjaftueshme.
TheksimetPërcaktoni se çfarë kërkon theksim në tekst. Zakonisht, kjo është rruga në ndërfaqe, butonat, shkurtimet e kodit, skedarët konfiguruese, blloqet "Kujdesi ju lutem". Vendosni se si do të jenë theksimet e këtyre elementeve dhe vendosni atë në rregullore. Mbani në mend se sa më pak theksime, aq më mirë. Kur ka shumë, teksti "bënë zhurmë". Zhurma krijohet madje edhe nga thonjtë, nëse përdoren shumë shpesh.
Screenshot-eBashkëpunoni me ekipin tuaj për të përcaktuar se në cilat raste nevojiten screenshot-e. Ilustruar çdo hap në mënyrë të saktë nuk është e nevojshme. Një numër i madh screenshot-esh, përfshirë butonat e veçantë, pengon perceptimin, prish dizajnin. Përcaktoni madhësinë, si dhe format e theksimeve dhe nënshkrimeve në screenshot-e, regulloni ato në rregullore. Kujdesuni që ilustarimet gjithmonë të përputhen me atë që është shkruar dhe të jenë aktuale. Sërish, nëse produkti përditësohet rregullisht, ndjekja e çdo ndryshimi do të jetë e vështirë.
Gjatësia e tekstit. Shmangni mbi artikujt shumë të gjatë. Ndajini ata në pjesë, dhe nëse nuk është e mundur, shtoni një përmbajtje me lidhje ankolike në fillim të artikujve. Një mënyrë e thjeshtë për ta bërë artikullin të duket vizualisht më i shkurtër është të fshihet detajet teknike, të cilat janë të nevojshme për një grup të ngushtë lexuesish, nën një spoiler.
Formate. Kombinoni disa formate në artikuj: tekst, video dhe imazhe. Kjo do ta përmirësojë perceptimin.
Mos u përpiqni të mbuloni problemet me dizajn të bukur. Sinqerisht, ne vetë shpresonim se "pakoja" do ta shpëtonte dokumentacionin e vjetruar - por nuk ndodhi. Në tekstet kishte kaq shumë zhurmë vizuale dhe detaje të panevojshme, saqë rregullorja dhe dizajni i ri ishin të pamjaftueshme.
Shumë nga ato që u përmenden më sipër do të përcaktohen nga platforma që po përdorni për dokumentacionin. Për ne, për shembull, është Confluence. Kemi pasur gjithashtu disa vështirësi me të. Nëse jeni të interesuar, lexoni tregimin e zhvilluesit tonë të uebit: .
Nga duhet të filloni përmirësimet dhe si të mbijetoni
Nëse dokumentacioni juaj është po aq i gjerë sa ai i ISPsystem dhe nuk dini nga të filloni, filloni me problemet më serioze. Klientët nuk kuptojnë dokumentacionin - meruni me përmirësimin e teksteve, krijoni rregullore, trajnojnë shkruesit. Dokumentacioni nuk është i përditësuar - meruni me proceset e brendshme. Filloni me artikujt më të njohur për produktet më të kërkuara: pyesni mbështetjes, shikoni analizat e faqes dhe kërkesat në motorët e kërkimit.
Të themi të drejtën - nuk do të jetë e lehtë. Dhe gjithashtu, shpejt nuk do të ndodhë. Përveç nëse sapo keni filluar dhe e bëni gjithçka siç duhet nga fillimi. Një gjë e dimë me siguri - me kalimin e kohës do të bëhet më mirë. Por procesi nuk do të përfundojë kurrë :-).
Burimi: habr.com
