Dokimantasyon lojisyèl se jis yon seri atik. Men, menm yo ka fè ou fou. Premyèman, ou pase yon bon bout tan kap chèche enstriksyon ki nesesè yo. Lè sa a, ou konprann tèks la fènwa. Ou fè jan sa ekri a, men pwoblèm nan pa rezoud. Ou chèche yon lòt atik, ou vin nève... Yon èdtan apre ou abandone tout bagay epi ale. Sa a se ki jan move dokiman travay. Ki sa ki fè li tankou sa a ak ki jan yo ranje li - li anba koupe a.
Te gen anpil enpèfeksyon nan ansyen dokiman nou an. Nou te retravay li pou prèske yon ane kounye a pou ke senaryo ki dekri pi wo a pa afekte kliyan nou yo. Gade, и .
Pwoblèm 1: Atik ki pa klè, mal ekri
Si dokiman an enposib pou konprann, ki pwen li genyen? Men, pesonn pa ekri atik enkonpreyansib espre. Yo rive lè otè a pa panse sou odyans lan ak objektif, vide dlo epi li pa tcheke tèks la pou erè.
- Odyans. Anvan ou ekri yon atik, ou bezwen reflechi sou nivo preparasyon lektè a. Li lojik ke nan yon atik pou yon debutan ou pa ta dwe sote etap debaz yo epi kite tèm teknik san eksplikasyon, men nan yon atik sou yon karakteristik ki ra ke pwofesyonèl sèlman bezwen, ou ta dwe eksplike siyifikasyon an nan mo PHP.
- Objektif. Yon lòt bagay pou w panse davans. Otè a dwe fikse yon objektif klè, detèmine efè itil atik la, epi deside kisa lektè a pral fè apre li fin li. Si sa a pa fè, ou pral fini ak deskripsyon pou dedomajman pou deskripsyon.
- Dlo ak pinèz. Gen anpil enfòmasyon ki pa nesesè ak biwokrasi, erè ak typo entèfere ak pèsepsyon. Menm si lektè a se pa yon nazi gramè, neglijans nan tèks la ka fèmen l '.
Konsidere konsèy ki anwo yo, epi atik yo ap vin pi klè - garanti. Pou fè li menm pi bon, sèvi ak nou an .
Pwoblèm 2. Atik yo pa reponn tout kesyon
Li pa bon lè dokiman an pa kenbe ak devlopman, pa reponn kesyon reyèl, ak erè nan li yo pa korije pou ane. Sa yo se pwoblèm pa tèlman nan otè a, men nan òganizasyon an nan pwosesis nan konpayi an.
Dokimantasyon pa kenbe ak devlopman
Karakteristik la deja nan lage, maketing plan yo kouvri li, ak Lè sa a, li vire soti ke nouvo atik la oswa tradiksyon se toujou pa nan dokiman an. Nou menm te oblije ranvwaye liberasyon an poutèt sa. Ou ka mande tout moun pou yo remèt travay yo bay ekriven teknik alè otan ke ou vle, men li p ap travay. Si pwosesis la pa otomatik, sitiyasyon an ap repete tèt li.
Nou te fè chanjman nan YouTrack. Travay la nan ekri yon atik sou yon nouvo karakteristik tonbe nan ekriven teknik la nan menm moman an lè karakteristik nan kòmanse teste. Lè sa a, maketing aprann sou li yo nan lòd yo prepare pou pwomosyon. Notifikasyon yo vini tou nan mesaje antrepriz Mattermost, kidonk li tou senpleman enposib pou rate nouvèl ki soti nan devlopè yo.
Dokimantasyon pa reflete demann itilizatè yo
Nou abitye travay konsa: yon karakteristik soti, nou te pale sou li. Nou te dekri kijan pou limen li, etenn li, epi fè bon ajisteman. Men, e si yon kliyan sèvi ak lojisyèl nou an nan yon fason nou pa t 'atann? Oswa èske li gen erè ke nou pa t 'panse a?
Pou asire ke dokiman an konplè ke posib, nou rekòmande analize demann sipò, kesyon sou fowòm tematik, ak demann nan motè rechèch. Sijè ki pi popilè yo pral transfere nan ekriven teknik pou yo ka konplete atik ki deja egziste oswa ekri nouvo.
Dokimantasyon pa amelyore
Li difisil pou fè li parfe touswit ap toujou gen erè. Ou ka espere pou fidbak nan men kliyan, men li se fasil ke yo pral rapòte chak typo, inexactitude, atik enkonpreyansib oswa enkonpreyansib. Anplis kliyan, anplwaye yo li dokiman an, ki vle di yo wè menm erè yo. Sa a ka itilize! Ou jis bezwen kreye kondisyon kote li pral fasil pou rapòte yon pwoblèm.
Nou gen yon gwoup sou pòtal entèn kote anplwaye yo kite kòmantè, sijesyon ak lide sou dokiman. Ăske sipò bezwen yon atik, men li pa egziste? Ăske tèsteur a remake erè a? Ăske patnè a pote plent bay administratè devlopman yo sou erè? Tout moun nan gwoup sa a! Ekriven teknik yo ranje kèk bagay touswit, transfere kèk bagay sou YouTrack, epi bay lòt moun kèk tan pou yo reflechi sou yo. Pou anpeche sijè a mouri, de tan zan tan nou raple w egzistans gwoup la ak enpòtans fidbak la.
Pwoblèm 3. Li pran anpil tan pou jwenn bon atik la.
Yon atik ki pa ka jwenn pa pi bon pase yon atik ki pa ka jwenn. Deviz bon dokiman yo ta dwe "Fasil pou chèche, fasil pou jwenn." Ki jan yo reyalize sa a?
Ăganize estrikti a epi detèmine prensip pou chwazi sijè. Estrikti a ta dwe transparan ke posib pou lektè a pa panse, "Ki kote mwen ka jwenn atik sa a?" Pou rezime, gen de apwòch: soti nan koòdone a ak nan travay yo.
- Soti nan koòdone a. Kontni an kopi seksyon panèl yo. Sa a te ka a nan ansyen dokiman ISPsystem la.
- Soti nan travay. Tit atik ak seksyon yo reflete travay itilizatè yo; Tit prèske toujou gen vèb ak repons pou kesyon "kijan pou yo". Koulye a, nou ap deplase nan fòma sa a.
Kèlkeswa apwòch ou chwazi a, asire w ke sijè a gen rapò ak sa itilizatè yo ap chèche epi li kouvri nan yon fason ki adrese espesyalman kesyon itilizatè a.
Mete kanpe yon rechèch santralize. Nan yon monn ideyal, rechèch ta dwe travay menm lè w mal òtograf oswa fè yon erè ak lang nan. Rechèch nou an nan Confluence jiskaprezan pa ka fè nou plezi ak sa. Si ou gen anpil pwodwi ak dokiman an jeneral, adapte rechèch la nan paj itilizatè a sou li. Nan ka nou an, rechèch la sou paj prensipal la ap travay pou tout pwodwi yo, epi si ou deja nan yon seksyon espesifik, Lè sa a, sèlman pou atik yo nan li.
Ajoute kontni ak ti pen. Li bon lè chak paj gen yon meni ak ti pen - chemen itilizatè a nan paj aktyèl la ak kapasite pou retounen nan nenpòt nivo. Nan ansyen dokiman ISPsystem la, ou te oblije sòti atik la pou w ale nan kontni an. Li te enkonvenyan, kidonk nou te fikse li nan nouvo a.
Mete lyen nan pwodwi a. Si moun vin sipòte sou yo ak sou ankò ak menm kesyon an, li fè sans yo ajoute yon allusion ak solisyon li yo nan koòdone la. Si ou gen done oswa insight sou lè yon itilizatè ap fè eksperyans yon pwoblèm, ou ka fè yo konnen tou ak yon lis adrès. Montre yo enkyetid epi retire fado a sou sipò.
Sou bò dwat la nan fenèt pop-up la se yon lyen ki mennen nan yon atik sou mete kanpe DNSSEC nan seksyon an jesyon domèn nan ISPmanager.
Mete referans kwaze nan dokiman an. Atik ki gen rapò youn ak lòt ta dwe "lye". Si atik yo se sekans, asire w ou ajoute flèch devan ak dèyè nan fen chak tèks.
Gen plis chans, yon moun pral premye ale chèche yon repons a kesyon li pa pou ou, men nan yon motè rechèch. Se yon wont si pa gen lyen ki mennen nan dokiman an la pou rezon teknik. Se konsa, pran swen optimize motè rechèch la.
Pwoblèm 4. Layout demode entèfere ak pèsepsyon
Anplis de tèks move, dokiman yo ka gate pa konsepsyon. Moun yo abitye li materyèl ki byen ekri. Blogs, rezo sosyal, medya - tout kontni prezante pa sèlman bèl, men tou, fasil pou li ak plezi nan je la. Se poutèt sa, ou ka fasilman konprann doulè a âânan yon moun ki wè tèks tankou nan ekran ki anba a.
Gen anpil Ekran ak en nan atik sa a ke yo pa ede, men sèlman entèfere ak pèsepsyon (foto a se klike sou)
Ou pa ta dwe fè yon long lekti nan dokiman an ak yon pakèt moun sou efè, men ou bezwen pran an kont règ debaz yo.
Layout. Detèmine lajè tèks kò a, font, gwosè, tit, ak padding. Anboche yon designer, epi aksepte travay la oswa fè li tèt ou, li liv Artyom Gorbunov la "Tipografi ak Layout." Li prezante sèlman yon gade nan Layout la, men li se byen ase.
Alokasyon. Detèmine sa ki mande aksan nan tèks la. Tipikman sa a se yon chemen nan koòdone a, bouton, foure kòd, fichye konfigirasyon, "Tanpri sonje" blòk. Detèmine ki alokasyon eleman sa yo pral epi anrejistre yo nan règleman yo. Kenbe nan tèt ou ke egzeyat la mwens, pi bon an. Lè gen anpil ladan yo, tèks la fè bwi. Menm guillemets kreye bri si yo itilize twò souvan.
Ekran. Dakò ak ekip la nan ki ka Ekran ki nesesè. Pa gen okenn nesesite pou ilistre chak etap. Yon gwo kantite Ekran, enkli. bouton separe, entèfere ak pèsepsyon, gate layout la. Detèmine gwosè a, osi byen ke fòma en ak siyati sou Ekran, epi anrejistre yo nan règleman yo. Sonje ke ilistrasyon yo ta dwe toujou koresponn ak sa ki ekri epi yo dwe enpòtan. Yon fwa ankò, si pwodwi a mete ajou regilyèman, li pral difisil pou kenbe tras de tout moun.
Longè tèks. Evite atik ki twò long. Kraze yo an pati, epi si sa a pa posib, ajoute kontni ak lyen jete lank nan kòmansman atik la. Yon fason senp pou fè yon atik vizyèlman pi kout se kache detay teknik ki nesesè pa yon sèk etwat nan lektè anba yon beke.
Fòma yo. Konbine plizyè fòma nan atik ou yo: tèks, videyo ak imaj. Sa a pral amelyore pèsepsyon an.
Pa eseye kouvri pwoblèm ak bèl layout. Onètman, nou menm nou te espere ke "anbalaj la" ta sove dokiman an demode - li pa t travay deyò. Tèks yo te genyen anpil bri vizyèl ak detay ki pa nesesè ke règleman yo ak nouvo konsepsyon yo te san fòs.
Anpil nan sa ki anwo yo pral detèmine pa platfòm ou itilize pou dokiman an. Pa egzanp, nou gen Confluence. Mwen te oblije jwe avè l 'tou. Si w enterese, li istwa pwomotè entènèt nou an: .
Ki kote yo kòmanse amelyore ak ki jan yo siviv
Si dokiman ou a vas tankou ISPsystem la epi ou pa konnen ki kote pou kòmanse, kòmanse ak pi gwo pwoblèm yo. Kliyan yo pa konprann dokiman an - amelyore tèks yo, fè règleman, fòme ekriven. Dokimantasyon yo demode - pran swen pwosesis entèn yo. Kòmanse ak atik ki pi popilè sou pwodwi ki pi popilè yo: mande sipò, gade analiz sit ak demann nan motè rechèch.
Ann di touswit - li pa pral fasil. Epi li fasil pou travay byen vit swa. Sòf si ou fèk kòmanse epi fè sa ki dwat touswit. Youn nan bagay nou konnen pou asire w se ke li pral vin pi bon sou tan. Men, pwosesis la pap janm fini :-).
Sous: www.habr.com
