Dokumentacioni i software-it është thjesht një grup artikujsh. Por edhe ata mund të jenë frustruese. Fillimisht, kërkoni gjatë për udhëzimin e nevojshëm. Pastaj, kuptoni një tekst të paqartë. Bëni siç është shkruar, por problemi nuk zgjidhert. Kërkoni një artikull tjetër, nervozoheni... Pas një ore, e braktisni gjithçka dhe largohemi. Kështu funksionon dokumentacioni i keq. Çfarë e bën atë të tillë dhe si ta rregulloni - lexoni më poshtë.
Në dokumentacionin tonë të vjetër kishte shumë mangësi. Që gati një vit, ne po e ripunojmë atë, për të siguruar që skenari i përshkruar më sipër të mos lidhet me klientët tanë. Shikoni, dhe .
Problemi 1. Artikuj të paqartë dhe keqshkruar
Nëse nuk mund të kuptoni dokumentacionin, çfarë kuptimi ka? Por askush nuk shkruan artikuj të paqartë qëllimisht. Ata ndodhin kur autori nuk mendon për audiencën dhe qëllimin, shkruan pa thelb dhe nuk e kontrollon tekstin për gabime.
- Audienca. Para ta shkrimit të një artikulli, duhet të mendohet për nivelin e përgatitjes së lexuesit. Ka kuptim që në një artikull për fillestarët nuk duhet të kalohen hapat bazikë dhe të lihen termat teknikë pa shpjegim, ndërsa në një artikull për një veçori të rrallë, të nevojshme vetëm për profesionistët, duhet të shpjegohet kuptimi i fjalës PHP.
- Qëllimi. Një tjetër gjë për të cilën është më mirë të mendoni më përpara. 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 leximit të tij. Nëse kjo nuk bëhet, do të rezultojë në një përshkrim vetëm për të përshkruar.
- Uji dhe gabimet. Informacioni i tepërt dhe fjalitë burokratike, gabimet dhe shtypjet e gabuara pengojnë përthithjen. Edhe nëse lexuesi nuk është një gramafobi, neglizha në tekst mund ta largojë atë.
Konsideroni këshillat e mësipërme, dhe artikujt do të bëhen më të qartë — garantuar. Për ta bërë edhe më mirë, merrni parasysh .
Problemi 2. Artikujt nuk përgjigjen në të gjitha pyetjet
Është keq kur dokumentacioni nuk arrin të ndjekë zhvillimin, nuk përgjigjet në pyetje reale, gabimet në të nuk korrigjohen për vite me radhë. Këto janë probleme jo aq shumë të autorit, sa të organizimit të proceseve brenda kompanisë.
Dokumentacioni nuk e ndjek zhvillimin
Tipari është tashmë në versionin e lirimit, marketingu planifikon ta përmendë, dhe këtu del se nuk ka ende një artikull të ri ose përkthim në dokumentacion. Kjo na ka detyruar të shtyjmë lançimin. Mund të kërkoni pa fund nga të gjithë që të dërgojnë detyrat te shkruesit teknikë në kohë, por kjo nuk do të funksionojë. Nëse procesi nuk automatizohet, situata do të përsëritet.
Ne bëri ndryshime në YouTrack. Detyra për të shkruar një artikull për tiparin e ri i shkon shkruesit teknik në momentin kur opsioni fillon të testohet. Atëherë marketingu merr informacionin për të përgatitur promovimin. Njoftimet gjithashtu vijnë në messenger-in korporativ Mattermost, kështu që është e pamundur të humbasësh lajmet nga zhvilluesit.
Dokumentacioni nuk pasqyron kërkesat e përdoruesve
Ne jemi mësuar të punojmë kështu: tipari doli, ne flasim për të. E përshkruajmë si ta aktivizojmë, çaktivizojmë, bëjmë rregullimet e imta. Por, çfarë ndodh nëse klienti e përdor softuerin tonë në mënyrë ndryshe nga sa ne kishim supozuar? Ose ndodh që ai të kenë gabime për të cilat ne nuk kemi menduar?
Për të pasur një dokumentacion sa më të plotë, sugjerojmë të analizoni kërkesat në mbështetje, pyetjet në forume tematike dhe kërkesat në motorët e kërkimit. Temat më populore t'i dërgoni shkruesve teknikë, për t'i plotësuar artikujt ekzistues ose për të shkruar të rinj.
Dokumentacioni nuk përmirësohet
Është e vështirë të bëhet gjithçka perfekt të parën herë, gabimet do të ekzistojnë gjithsesi. Mund të shpresoni për feedback nga klientët, por është e vështirë që ata të raportojnë për çdo gabim shkrimi, pasaktësi, artikuj të paqartë ose të paqarta. Pavarësisht klientëve, dokumentacionin e lexojnë edhe punonjësit, prandaj ata do të shohin të njëjtat gabime. Kjo mund të shfrytëzohet! Duhet vetëm të krijoni kushte në të cilat do të jetë e lehtë të raportoni një problem.
Ne kemi një grup në portalin tonë të brendshëm, ku punonjësit lënë vërejtje, propozime dhe ide mbi dokumentacionin. Po i nevojitet një artikull mbështetjes, por nuk ka? Një testues vuri re një pasaktësi? Një partner u ankuar menaxherëve të zhvillimit për gabime? Të gjitha këto shkojnë në këtë grup! Shkrimtarët teknikë korrigjojnë diçka menjëherë, disa çështje i transferojnë në YouTrack, disa i marrin për t'i menduar. Që tema të mos heshtet, herë pas here ne kujtojmë ekzistencën e grupit dhe rëndësinë e reagimeve.
Problemi 3. Artikulli i nevojshëm duhet të kërkohet gjatë
Një artikull që nuk mund të gjendet nuk është ndryshe nga një artikull që nuk ekziston. Moti i mirë mbi dokumentacionin duhet të jetë fjala "E lehtë për t'u kërkuar, e lehtë për t'u gjetur". Si mund ta arritim këtë?
Renditni strukturën dhe përcaktoni parimin e изборit të temave. Struktura duhet të jetë sa më e qartë, në mënyrë që lexuesi të mos mendojë "Ku mund ta gjej këtë artikull?". Nëse e përmbledh, ka dy qasje: nga ndërfaqja dhe nga detyrat.
- Nga ndërfaqja. Përmbajtja e dyfishon seksionet e panelit. Kështu ishte në dokumentacionin e vjetër ISPsystem.
- Nga detyrat. Titujt e artikujve dhe seksioneve reflektojnë detyrat e përdoruesve; në tituj pothuajse gjithmonë ka folje dhe përgjigje në pyetjen "si të bëhet". Tani ne po kalojmë në një format të tillë.
Pavarësisht nga qasja që zgjidhni, sigurohuni që tema të përputhet me kërkesat e përdoruesve dhe të jetë trajtuar në mënyrë që përdoruesi të zgjidhë padyshim problemin e tij.
Për të vendosur një kërkim të centralizuar. Në një botë ideale, kërkimi duhet të funksionojë edhe kur gabohesh ose bësh një gabim në gjuhë. Kërkimi ynë në Confluence ende nuk mund të sigurojë këtë. Nëse keni shumë produkte dhe dokumentacioni është i përgjithshëm, përshtatni kërkimin sipas faqes ku ndodhet përdoruesi. Në rastin tonë, kërkimi në kreun e faqes punon për të gjitha produktet, por nëse jeni tashmë në një seksion të caktuar, atëherë vetëm për artikujt në të.
Shto përmbajtjen dhe "brumbujt e bukës". Mirë është që në çdo faqe të ketë një menu dhe brumbuj të bukës — rruga e përdoruesit deri në këtë faqe me mundësinë për t'u rikthyer në çdo nivel. Në dokumentacionin e vjetër të ISPsystem, duhej të dilje nga artikulli për të hyrë në përmbajtje. Ka qenë e papërshtatshme, kështu që në të rejn e kemi përmirësuar këtë.
Vendos lidhjet në produkt. Nëse njerëzit vazhdimisht paraqiten në mbështetje me të njëjtën pyetje, është e arsyeshme të shtoni një sugjerim me zgjidhjen e saj në ndërfaqe. Nëse keni të dhëna ose kuptim se në cilin moment përdoruesi përballet me një problem, gjithashtu mund ta njoftoni atë me një dërgesë. Kështu, tregoni kujdes dhe reduktoni ngarkesën në mbështetje.
Në të djathtën e dritares së pop-up është një lidhje për artikullin mbi konfigurimin e DNSSEC në seksionin e menaxhimit të domain-eve në ISPmanager
Konfiguroni lidhjet ndërmjet dokumenteve. Artikujt që lidhen me njëri-tjetrin duhet të jenë 'të lidhur'. Nëse artikujt përbëjnë një rend, sigurohuni të shtoni në fund të çdo teksti shigjeta përpara dhe prapa.
Është e mundshme që personi fillimisht do të shkojë të kërkojë përgjigjen për pyetjen e tij jo te ju, por në një motor kërkimi. Është e dhimbshme nëse nuk ka lidhje në dokumentacion për arsye teknike. Prandaj, kujdesuni për optimizimin e motorëve të kërkimit.
Problemi 4. Dizajni i vjetër pengon perceptimin
Përveç teksteve të dobët, dizajni mund ta prishë dokumentacionin. Njerëzit janë mësuar të lexojnë materiale të mirëstrukturuara. Bloget, rrjetet sociale, mediat — të gjitha përmbajtjet paraqiten jo vetëm bukur, por edhe të lehta për t'u lexuar dhe të këndshme për sy. Prandaj, mund të kuptohet lehtë dhimbja e personit që sheh tekstin si në screenshotin më poshtë.
Në këtë artikull ka kaq shumë screenshot-e dhe theksime saqë ato nuk ndihmojnë, vetëm pengojnë perceptimin (imazhi është i klikueshëm)
Nuk duhet të bëni nga dokumentacioni një longread me shumë efekte, por duhet të keni parasysh rregullat bazë.
Strukturimi. Përcaktoni gjerësinë e tekstit kryesor, fontin, madhësinë, titujt dhe distancat. Angazhoni një dizajner, dhe që të pranoni punën ose për ta menaxhuar vetë, lexoni librin e Artem Gorbunov «Tipografia dhe Strukturimi». Në të paraqitet vetëm një nga këndvështrimet mbi strukturimin, por është plotësisht i mjaftueshëm.
Theksime. Përcaktoni se çfarë kërkon theksime në tekst. Zakonisht, kjo është rruga në ndërfaqe, butonat, pjesët e kodit, skedarët e konfigurimit, blloqet "Kujdesi". Caktoni se si do të jenë theksimet e këtyre elementeve dhe regjistrojeni në rregullore. Kini parasysh se sa më pak theksime, aq më mirë. Kur ka shumë, teksti bëhet "i zhurmshëm". Edhe thonjëzat shkaktojnë zhurmë nëse përdoren shumë shpesh.
Screenshot-e. Rini dakord me ekipin për rastet kur nevojiten screenshot-e. Ilustruar çdo hap saktësisht nuk është e nevojshme. Një numër i madh screenshot-esh, përfshirë butonat e veçantë, pengon perceptimin dhe prish dizajnin. Përcaktoni madhësinë, si dhe format e theksimeve dhe nënshkrimeve në screenshot-e, dhe regjistrojeni në rregullore. Mbani mend se ilustrimet gjithmonë duhet të përputhen me atë që është shkruar dhe të jenë aktuale. Përsëri, nëse produkti përditësohet vazhdimisht, do të jetë e vështirë të ndiqni çdo ndryshim.
Gjatësia e tekstit. Shmangni artikuj të gjatë. Ndani ato në pjesë, dhe nëse është e pamundur, shtoni përmbajtje me lidhje ankolike në fillim të artikullit. Një mënyrë e thjeshtë për ta bërë artikullin vizualisht më të shkurtër është të fshihni 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 të përmirësojë perceptimin.
Mos përpiquni të mbuloni problemet me një dizajn të bukur. Sinqerisht, edhe ne shpresonim se 'ndërlikuar' do të shpëtonte dokumentacionin e vjetëruar - por nuk ndodhi. Në tekst ishte kaq shumë zhurmë vizuale dhe detaje të tepërta, saqë rregullorja dhe dizajni i ri ishin të pafuqishëm.
Shumë nga ato që përmenden më sipër do të përcaktohen nga platforma që përdorni për dokumentacionin. Për ne, për shembull, është Confluence. Me të gjithashtu duhej punuar. Nëse jeni të interesuar, lexoni tregimin e zhvilluesit tonë të uebit: .
Nga të filloni përmirësimet dhe si të mbijetoni
Nëse dokumentacioni juaj është po aq i gjerë sa ai i ISPsystem, dhe nuk e dini nga të filloni, filloni me problemet më të rënda. Klientët nuk e kuptojnë dokumentacionin — përmirësoni tekstet, krijoni rregulla, trajnojini shkrimtarët. Dokumentacioni është i paazhorituar — meruni me proceset e brendshme. Filloni me artikujt më të njohur rreth produkteve më të kërkuara: pyesni mbështetje, shikoni analitikën e faqes dhe kërkesat në motorët e kërkimit.
Të drejtat e para — nuk do të jetë e lehtë. As shpejt nuk do të tregojë rezultat. Përveç nëse sapo keni filluar dhe bëni gjithçka si duhet menjëherë. Një gjë e dimë me siguri — me kalimin e kohës do të përmirësohet. Por procesi nuk do të mbarojë kurrë :-).
Burimi: habr.com
