Dokumentacioni i softuerit është vetëm një grup artikujsh. Por edhe ata mund t'ju çmendin. Së pari, kaloni një kohë të gjatë duke kërkuar udhëzimet e nevojshme. Atëherë e kuptoni tekstin e errët. Ju bëni siç është shkruar, por problemi nuk zgjidhet. Kërkon një artikull tjetër, nervozohesh... Një orë më vonë heq dorë nga gjithçka dhe largohesh. Kështu funksionon dokumentacioni i keq. Çfarë e bën atë të tillë dhe si ta rregulloni - lexoni nën prerje.
Në dokumentacionin tonë të vjetër kishte shumë mangësi. Ne e kemi ripunuar atë për gati një vit tani në mënyrë që skenari i përshkruar më sipër të mos prekë klientët tanë. Shikoni, и .
Problemi 1: Artikuj të paqartë, të shkruar keq
Nëse dokumentacioni është i pamundur të kuptohet, cili është qëllimi i tij? Por askush nuk shkruan me qëllim artikuj të pakuptueshëm. Ato ndodhin kur autori nuk mendon për audiencën dhe qëllimin, derdh ujë dhe nuk e kontrollon tekstin për gabime.
- audiencë. Para se të shkruani një artikull, duhet të mendoni për nivelin e përgatitjes së lexuesit. Është logjike që në një artikull për një fillestar të mos kaloni hapat bazë dhe të lini termat teknike pa shpjegim, por në një artikull për një veçori të rrallë që u nevojitet vetëm profesionistëve, duhet të shpjegoni kuptimin e fjalës PHP.
- Qëllim. Një gjë tjetër për të menduar paraprakisht. Autori duhet të vendosë një qëllim të qartë, të përcaktojë efektin e dobishëm të artikullit dhe të vendosë se çfarë do të bëjë lexuesi pasi ta lexojë atë. Nëse kjo nuk bëhet, do të përfundoni me përshkrim për hir të përshkrimit.
- Uji dhe insektet. Ka shumë informacione të panevojshme dhe burokracia, gabimet dhe gabimet e shtypit ndërhyjnë në perceptimin. Edhe nëse lexuesi nuk është nazist gramatikor, pakujdesia në tekst mund ta shuajë atë.
Merrni parasysh këshillat e mësipërme dhe artikujt do të bëhen më të qartë - të garantuar. Për ta bërë atë edhe më të mirë, përdorni tonë .
Problemi 2. Artikujt nuk u përgjigjen të gjitha pyetjeve
Është keq kur dokumentacioni nuk shkon në hap me zhvillimin, nuk u përgjigjet pyetjeve reale dhe gabimet në të nuk korrigjohen me vite. Këto janë probleme jo aq të autorit, por të organizimit të proceseve brenda kompanisë.
Dokumentacioni nuk shkon në hap me zhvillimin
Veçoria është tashmë në qarkullim, marketingu planifikon ta mbulojë atë dhe më pas rezulton se artikulli ose përkthimi i ri nuk është ende në dokumentacion. Madje na u desh ta shtynim lëshimin për shkak të kësaj. Ju mund t'i kërkoni të gjithëve që t'ua dorëzojnë detyrat shkrimtarëve teknikë në kohë sa të doni, por nuk do të funksionojë. Nëse procesi nuk është i automatizuar, situata do të përsëritet.
Ne kemi bërë ndryshime në YouTrack. Detyra për të shkruar një artikull për një veçori të re i bie shkrimtarit teknik në të njëjtin moment kur funksioni fillon të testohet. Pastaj marketingu mëson për të në mënyrë që të përgatitet për promovim. Njoftimet vijnë gjithashtu në mesazherin e korporatës Mattermost, kështu që është thjesht e pamundur të humbasësh lajmet nga zhvilluesit.
Dokumentacioni nuk pasqyron kërkesat e përdoruesve
Jemi mësuar të punojmë kështu: doli një veçori, folëm për të. Ne përshkruam se si ta ndizni, ta fikni dhe të bëni rregullime të shkëlqyera. Por, çka nëse një klient përdor softuerin tonë në një mënyrë që ne nuk e prisnim? Apo ka gabime që nuk i kemi menduar?
Për të siguruar që dokumentacioni të jetë sa më i plotë që të jetë e mundur, ne rekomandojmë analizimin e kërkesave për mbështetje, pyetjeve në forume tematike dhe pyetjeve në motorët e kërkimit. Temat më të njohura do t'u transferohen shkrimtarëve teknikë në mënyrë që ata të mund të plotësojnë artikujt ekzistues ose të shkruajnë të rinj.
Dokumentacioni nuk po përmirësohet
Është e vështirë ta bësh atë në mënyrë perfekte menjëherë; do të ketë ende gabime. Mund të shpresoni për reagime nga klientët, por nuk ka gjasa që ata të raportojnë çdo gabim shtypi, pasaktësi, artikull të pakuptueshëm ose të pagjetur. Përveç klientëve, punonjësit lexojnë dokumentacionin, që do të thotë se shohin të njëjtat gabime. Kjo mund të përdoret! Thjesht duhet të krijoni kushte në të cilat do të jetë e lehtë të raportoni një problem.
Ne kemi një grup në portalin e brendshëm ku punonjësit lënë komente, sugjerime dhe ide mbi dokumentacionin. A ka nevojë mbështetja për një artikull, por ai nuk ekziston? A e vuri re testuesi pasaktësinë? A është ankuar partneri te menaxherët e zhvillimit për gabime? Të gjithë në këtë grup! Shkrimtarët teknikë rregullojnë disa gjëra menjëherë, transferojnë disa gjëra në YouTrack dhe u japin të tjerëve pak kohë për të menduar. Për të parandaluar që tema të shuhet, herë pas here ju kujtojmë ekzistencën e grupit dhe rëndësinë e reagimeve.
Problemi 3. Duhet shumë kohë për të gjetur artikullin e duhur.
Një artikull që nuk mund të gjendet nuk është më i mirë se një artikull që nuk mund të gjendet. Motoja e dokumentacionit të mirë duhet të jetë "E lehtë për t'u kërkuar, e lehtë për t'u gjetur". Si të arrihet kjo?
Organizoni strukturën dhe përcaktoni parimin për zgjedhjen e temave. Struktura duhet të jetë sa më transparente në mënyrë që lexuesi të mos mendojë: "Ku mund ta gjej këtë artikull?" Për ta përmbledhur, ekzistojnë dy qasje: nga ndërfaqja dhe nga detyrat.
- Nga ndërfaqja. Përmbajtja kopjon seksionet e panelit. Ky ishte rasti në dokumentacionin e vjetër të sistemit ISP.
- Nga detyrat. Titujt e artikujve dhe seksioneve pasqyrojnë detyrat e përdoruesve; Titujt pothuajse gjithmonë përmbajnë folje dhe përgjigje për pyetjen "si të". Tani po kalojmë në këtë format.
Çfarëdo qasjeje që zgjidhni, sigurohuni që tema të jetë e përshtatshme me atë që përdoruesit kërkojnë dhe të mbulohet në një mënyrë që adreson në mënyrë specifike pyetjen e përdoruesit.
Vendosni një kërkim të centralizuar. Në një botë ideale, kërkimi duhet të funksionojë edhe kur ju shkruani gabim ose bëni një gabim me gjuhën. Kërkimi ynë në Confluence deri tani nuk mund të na kënaqë me këtë. Nëse keni shumë produkte dhe dokumentacioni është i përgjithshëm, përshtateni kërkimin në faqen në të cilën është përdoruesi. Në rastin tonë, kërkimi në faqen kryesore funksionon për të gjitha produktet, dhe nëse jeni tashmë në një seksion specifik, atëherë vetëm për artikujt në të.
Shtoni përmbajtjen dhe thërrimet e bukës. Është mirë kur secila faqe ka një menu dhe copëza buke - rruga e përdoruesit në faqen aktuale me aftësinë për t'u kthyer në çdo nivel. Në dokumentacionin e vjetër të sistemit ISP, duhej të dilje nga artikulli për të arritur te përmbajtja. Ishte e papërshtatshme, kështu që e rregulluam në të renë.
Vendosni lidhje në produkt. Nëse njerëzit vijnë për të mbështetur vazhdimisht me të njëjtën pyetje, ka kuptim të shtoni një sugjerim me zgjidhjen e tij në ndërfaqe. Nëse keni të dhëna ose njohuri se kur një përdorues po përjeton një problem, mund t'i njoftoni gjithashtu me një listë postimesh. Tregojuni atyre shqetësim dhe hiqni barrën nga mbështetja.
Në të djathtë në dritaren që shfaqet është një lidhje me një artikull rreth konfigurimit të DNSSEC në seksionin e menaxhimit të domenit të ISPmanager
Vendosni referenca të kryqëzuara brenda dokumentacionit. Artikujt që lidhen me njëri-tjetrin duhet të "lidhen". Nëse artikujt janë të njëpasnjëshëm, sigurohuni që të shtoni shigjeta përpara dhe prapa në fund të çdo teksti.
Me shumë mundësi, një person së pari do të kërkojë një përgjigje për pyetjen e tij jo për ju, por për një motor kërkimi. Është turp nëse nuk ka lidhje me dokumentacionin atje për arsye teknike. Pra, kujdesuni për optimizimin e motorëve të kërkimit.
Problemi 4. Paraqitja e vjetëruar ndërhyn me perceptimin
Përveç teksteve të këqija, dokumentacioni mund të prishet nga dizajni. Njerëzit janë mësuar të lexojnë materiale të shkruara mirë. Blogjet, rrjetet sociale, mediat - e gjithë përmbajtja paraqitet jo vetëm e bukur, por edhe e lehtë për t'u lexuar dhe e këndshme për syrin. Prandaj, mund ta kuptoni lehtësisht dhimbjen e një personi që sheh tekst si në pamjen e mëposhtme të ekranit.
Ka kaq shumë pamje nga ekrani dhe pika kryesore në këtë artikull sa ato nuk ndihmojnë, por vetëm ndërhyjnë në perceptimin (fotografia mund të klikohet)
Ju nuk duhet të bëni një kohë të gjatë nga dokumentacioni me një mori efektesh, por duhet të merrni parasysh rregullat bazë.
Paraqitja. Përcaktoni gjerësinë e tekstit në trup, fontin, madhësinë, titujt dhe mbushjen. Punësoni një stilist dhe për ta pranuar punën ose për ta bërë vetë, lexoni librin e Artyom Gorbunov "Tipografia dhe Layout". Ai paraqet vetëm një pamje të paraqitjes, por është mjaft e mjaftueshme.
Alokimet. Përcaktoni se çfarë kërkon theksim në tekst. Zakonisht kjo është një shteg në ndërfaqen, butonat, futjet e kodit, skedarët e konfigurimit, blloqet "Ju lutemi vini re". Përcaktoni se cilat do të jenë alokimet e këtyre elementeve dhe regjistrojini ato në rregullore. Mbani në mend se sa më pak shkarkim, aq më mirë. Kur ka shumë prej tyre, teksti është i zhurmshëm. Edhe thonjëzat krijojnë zhurmë nëse përdoren shumë shpesh.
Fotografitë. Pajtohu me ekipin në cilat raste nevojiten pamjet e ekranit. Sigurisht që nuk ka nevojë të ilustrohet çdo hap. Një numër i madh i pamjeve të ekranit, përfshirë. butona të veçantë, ndërhyjnë me perceptimin, prishin paraqitjen. Përcaktoni madhësinë, si dhe formatin e pikave kryesore dhe nënshkrimeve në pamjet e ekranit dhe regjistrojini ato në rregullore. Mos harroni se ilustrimet duhet gjithmonë të korrespondojnë me atë që është shkruar dhe të jenë të rëndësishme. Përsëri, nëse produkti përditësohet rregullisht, do të jetë e vështirë të mbash gjurmët e të gjithëve.
Gjatësia e tekstit. Shmangni artikujt tepër të gjatë. Ndani ato në pjesë dhe nëse nuk është e mundur, shtoni përmbajtje me lidhje ankorimi në fillim të artikullit. Një mënyrë e thjeshtë për ta bërë një artikull vizualisht më të shkurtër është fshehja e detajeve teknike të nevojshme nga një rreth i ngushtë lexuesish nën një spoiler.
Formatet. Kombinoni disa formate në artikujt tuaj: tekst, video dhe imazhe. Kjo do të përmirësojë perceptimin.
Mos u mundoni t'i mbuloni problemet me paraqitjen e bukur. Sinqerisht, ne vetë shpresonim që "mbështjellësi" do të ruante dokumentacionin e vjetëruar - nuk funksionoi. Tekstet përmbanin aq shumë zhurmë vizuale dhe detaje të panevojshme saqë rregulloret dhe dizajni i ri ishin të pafuqishëm.
Pjesa më e madhe e sa më sipër do të përcaktohet nga platforma që përdorni për dokumentacion. Për shembull, ne kemi Confluence. Edhe unë duhej të merresha me të. Nëse jeni të interesuar, lexoni historinë e zhvilluesit tonë të internetit: .
Ku të filloni të përmirësoheni dhe si të mbijetoni
Nëse dokumentacioni juaj është po aq i madh sa ai i sistemit ISP dhe nuk dini nga të filloni, filloni me problemet më të mëdha. Klientët nuk e kuptojnë dokumentin - përmirësoni tekstet, bëni rregullore, trajnoni shkrimtarë. Dokumentacioni është i vjetëruar - kujdesuni për proceset e brendshme. Filloni me artikujt më të njohur për produktet më të njohura: kërkoni mbështetje, shikoni analitikën e faqeve dhe pyetjet në motorët e kërkimit.
Le të themi menjëherë - nuk do të jetë e lehtë. Dhe nuk ka gjasa të funksionojë shpejt. Përveç nëse sapo filloni dhe bëni gjënë e duhur menjëherë. Një gjë që ne e dimë me siguri është se do të përmirësohet me kalimin e kohës. Por procesi nuk do të përfundojë kurrë :-).
Burimi: www.habr.com