વપરાશકર્તા દસ્તાવેજીકરણ: તેને શું ખરાબ બનાવે છે અને તેને કેવી રીતે ઠીક કરવું

સૉફ્ટવેર દસ્તાવેજીકરણ ફક્ત લેખોનો સમૂહ છે. પણ તેઓ તમને પાગલ બનાવી શકે છે. પ્રથમ, તમે જરૂરી સૂચનાઓ શોધવામાં લાંબો સમય પસાર કરો છો. પછી તમે અસ્પષ્ટ ટેક્સ્ટને સમજો છો. તમે લખ્યા પ્રમાણે કરો છો, પરંતુ સમસ્યા હલ થતી નથી. તમે બીજો લેખ શોધો છો, તમે ગભરાઈ જાઓ છો... એક કલાક પછી તમે બધું છોડી દો છો અને ચાલ્યા જાઓ છો. આ રીતે ખરાબ દસ્તાવેજીકરણ કામ કરે છે. તેને આના જેવું શું બનાવે છે અને તેને કેવી રીતે ઠીક કરવું - કટ હેઠળ વાંચો.

અમારા જૂના દસ્તાવેજોમાં ઘણી ખામીઓ હતી. અમે લગભગ એક વર્ષથી તેને ફરીથી કામ કરી રહ્યા છીએ જેથી ઉપર વર્ણવેલ દૃશ્ય અમારા ગ્રાહકોને અસર ન કરે. જુઓ, જેવું હતું તેવું и એ કેવી રીતે થયું.

સમસ્યા 1: અસ્પષ્ટ, ખરાબ રીતે લખાયેલા લેખો

જો દસ્તાવેજીકરણ સમજવું અશક્ય છે, તો તેનો અર્થ શું છે? પરંતુ હેતુપૂર્વક કોઈ અગમ્ય લેખો લખતું નથી. તે ત્યારે થાય છે જ્યારે લેખક પ્રેક્ષકો અને હેતુ વિશે વિચારતો નથી, પાણી રેડે છે અને ભૂલો માટે ટેક્સ્ટને તપાસતો નથી.

• પ્રેક્ષકો. લેખ લખતા પહેલા, તમારે વાચકની તૈયારીના સ્તર વિશે વિચારવાની જરૂર છે. તે તાર્કિક છે કે શિખાઉ માણસ માટેના લેખમાં તમારે મૂળભૂત પગલાંને છોડવું જોઈએ નહીં અને સમજૂતી વિના તકનીકી શરતો છોડવી જોઈએ નહીં, પરંતુ એક દુર્લભ વિશેષતા પરના લેખમાં જે ફક્ત વ્યાવસાયિકોને જ જોઈએ છે, તમારે PHP શબ્દનો અર્થ સમજાવવો જોઈએ.
• લક્ષ્ય. અગાઉથી વિચારવા માટે એક વધુ વસ્તુ. લેખકે સ્પષ્ટ લક્ષ્ય નક્કી કરવું જોઈએ, લેખની ઉપયોગી અસર નક્કી કરવી જોઈએ અને તે વાંચ્યા પછી વાચક શું કરશે તે નક્કી કરવું જોઈએ. જો આ કરવામાં ન આવે તો, તમે વર્ણન ખાતર વર્ણન સાથે સમાપ્ત થશો.
• પાણી અને ભૂલો. ત્યાં ઘણી બધી બિનજરૂરી માહિતી છે અને અમલદારશાહી, ભૂલો અને લખાણની ભૂલો ખ્યાલમાં દખલ કરે છે. જો વાચક વ્યાકરણ નાઝી ન હોય તો પણ, ટેક્સ્ટમાં બેદરકારી તેને બંધ કરી શકે છે.

ઉપરોક્ત ટીપ્સને ધ્યાનમાં લો, અને લેખો વધુ સ્પષ્ટ થશે - ખાતરીપૂર્વક. તેને વધુ સારું બનાવવા માટે, અમારો ઉપયોગ કરો તકનીકી દસ્તાવેજીકરણ પર કામ કરતી વખતે 50 પ્રશ્નો.

સમસ્યા 2. લેખો બધા પ્રશ્નોના જવાબ આપતા નથી

તે ખરાબ છે જ્યારે દસ્તાવેજીકરણ વિકાસ સાથે ચાલુ રાખતું નથી, વાસ્તવિક પ્રશ્નોના જવાબ આપતું નથી અને તેમાંની ભૂલોને વર્ષો સુધી સુધારી શકાતી નથી. આ સમસ્યાઓ લેખકની નથી, પરંતુ કંપનીમાં પ્રક્રિયાઓના સંગઠનની છે.

દસ્તાવેજીકરણ વિકાસ સાથે સુસંગત નથી

આ સુવિધા પહેલાથી જ રિલીઝમાં છે, માર્કેટિંગ તેને આવરી લેવાની યોજના ધરાવે છે, અને પછી તે તારણ આપે છે કે નવો લેખ અથવા અનુવાદ હજુ પણ દસ્તાવેજીકરણમાં નથી. આ કારણે અમારે રિલીઝ પણ મોકૂફ રાખવી પડી હતી. તમે દરેકને તમે ઇચ્છો તેટલા સમયસર ટેકનિકલ લેખકોને કાર્યો સોંપવા માટે કહી શકો છો, પરંતુ તે કામ કરશે નહીં. જો પ્રક્રિયા સ્વયંસંચાલિત નથી, તો પરિસ્થિતિ પોતાને પુનરાવર્તિત કરશે.

અમે YouTrack માં ફેરફારો કર્યા છે. નવી સુવિધા વિશે લેખ લખવાનું કાર્ય તે જ ક્ષણે તકનીકી લેખકને આવે છે જ્યારે સુવિધાનું પરીક્ષણ કરવાનું શરૂ થાય છે. પછી પ્રમોશનની તૈયારી કરવા માટે માર્કેટિંગ તેના વિશે શીખે છે. મેટરમોસ્ટ કોર્પોરેટ મેસેન્જર પર પણ સૂચનાઓ આવે છે, તેથી વિકાસકર્તાઓ તરફથી સમાચાર ચૂકી જવું અશક્ય છે.

દસ્તાવેજીકરણ વપરાશકર્તા વિનંતીઓને પ્રતિબિંબિત કરતું નથી

અમે આની જેમ કામ કરવા માટે ટેવાયેલા છીએ: એક લક્ષણ બહાર આવ્યું, અમે તેના વિશે વાત કરી. અમે તેને કેવી રીતે ચાલુ કરવું, તેને બંધ કરવું અને સરસ ગોઠવણો કરવી તે વર્ણવ્યું છે. પરંતુ જો કોઈ ક્લાયન્ટ અમારા સૉફ્ટવેરનો એવી રીતે ઉપયોગ કરે છે જેની અમને અપેક્ષા ન હોય તો? અથવા તેમાં એવી ભૂલો છે કે જેના વિશે આપણે વિચાર્યું નથી?

દસ્તાવેજીકરણ શક્ય તેટલું પૂર્ણ છે તેની ખાતરી કરવા માટે, અમે સપોર્ટ વિનંતીઓ, થીમ આધારિત ફોરમ પરના પ્રશ્નો અને શોધ એન્જિનમાં પ્રશ્નોનું વિશ્લેષણ કરવાની ભલામણ કરીએ છીએ. સૌથી વધુ લોકપ્રિય વિષયો તકનીકી લેખકોને સ્થાનાંતરિત કરવામાં આવશે જેથી તેઓ હાલના લેખોની પૂર્તિ કરી શકે અથવા નવા લખી શકે.

દસ્તાવેજીકરણમાં સુધારો થતો નથી

તે તરત જ સંપૂર્ણ રીતે કરવું મુશ્કેલ છે; હજી પણ ભૂલો હશે. તમે ગ્રાહકો પાસેથી પ્રતિસાદની આશા રાખી શકો છો, પરંતુ તે અસંભવિત છે કે તેઓ દરેક લખાણની ભૂલો, અચોક્કસતા, અગમ્ય અથવા ખોટા લેખની જાણ કરશે. ગ્રાહકો ઉપરાંત, કર્મચારીઓ દસ્તાવેજો વાંચે છે, જેનો અર્થ છે કે તેઓ સમાન ભૂલો જુએ છે. આનો ઉપયોગ કરી શકાય છે! તમારે ફક્ત એવી પરિસ્થિતિઓ બનાવવાની જરૂર છે જેમાં સમસ્યાની જાણ કરવી સરળ હશે.

અમારી પાસે આંતરિક પોર્ટલ પર એક જૂથ છે જ્યાં કર્મચારીઓ દસ્તાવેજીકરણ પર ટિપ્પણીઓ, સૂચનો અને વિચારો આપે છે. શું સમર્થનને લેખની જરૂર છે, પરંતુ તે અસ્તિત્વમાં નથી? શું પરીક્ષકે અચોક્કસતા ધ્યાનમાં લીધી? શું ભાગીદારે વિકાસ સંચાલકોને ભૂલો વિશે ફરિયાદ કરી છે? આ જૂથમાં બધા! ટેકનિકલ લેખકો તરત જ કેટલીક વસ્તુઓને ઠીક કરે છે, કેટલીક વસ્તુઓ YouTrack પર સ્થાનાંતરિત કરે છે અને અન્યને વિચારવા માટે થોડો સમય આપે છે. વિષયને મૃત્યુ પામતો અટકાવવા માટે, સમય સમય પર અમે તમને જૂથના અસ્તિત્વ અને પ્રતિસાદના મહત્વની યાદ અપાવીએ છીએ.

સમસ્યા 3. યોગ્ય લેખ શોધવામાં ઘણો સમય લાગે છે.

ન મળી શકે તેવો લેખ ન મળી શકે તેવા લેખ કરતાં વધુ સારો નથી. સારા દસ્તાવેજીકરણનું સૂત્ર "શોધવામાં સરળ, શોધવામાં સરળ" હોવું જોઈએ. આ કેવી રીતે હાંસલ કરવું?

માળખું ગોઠવો અને વિષયો પસંદ કરવા માટે સિદ્ધાંત નક્કી કરો. માળખું શક્ય તેટલું પારદર્શક હોવું જોઈએ જેથી કરીને વાચક એવું ન વિચારે કે "મને આ લેખ ક્યાંથી મળશે?" સારાંશ માટે, ત્યાં બે અભિગમો છે: ઇન્ટરફેસમાંથી અને કાર્યોમાંથી.

1. ઇન્ટરફેસમાંથી. સામગ્રી પેનલ વિભાગોની નકલ કરે છે. જૂના ISP સિસ્ટમ દસ્તાવેજીકરણમાં આ કેસ હતો.
2. કાર્યોમાંથી. લેખો અને વિભાગોના શીર્ષકો વપરાશકર્તાઓના કાર્યોને પ્રતિબિંબિત કરે છે; શીર્ષકો લગભગ હંમેશા "કેવી રીતે" પ્રશ્નના ક્રિયાપદો અને જવાબો ધરાવે છે. હવે આપણે આ ફોર્મેટ તરફ આગળ વધી રહ્યા છીએ.

તમે જે પણ અભિગમ પસંદ કરો છો, ખાતરી કરો કે વિષય વપરાશકર્તાઓ જે શોધી રહ્યાં છે તેનાથી સંબંધિત છે અને તે એવી રીતે આવરી લેવામાં આવે છે કે જે વપરાશકર્તાના પ્રશ્નને ખાસ સંબોધિત કરે છે.

કેન્દ્રિય શોધ સેટ કરો. આદર્શ વિશ્વમાં, જ્યારે તમે ખોટી જોડણી કરો છો અથવા ભાષા સાથે ભૂલ કરો છો ત્યારે પણ શોધ કાર્ય કરવી જોઈએ. સંગમમાં અમારી શોધ અત્યાર સુધી અમને આથી ખુશ કરી શકતી નથી. જો તમારી પાસે ઘણા ઉત્પાદનો છે અને દસ્તાવેજીકરણ સામાન્ય છે, તો વપરાશકર્તા જે પૃષ્ઠ પર છે તેના પર શોધને અનુરૂપ બનાવો. અમારા કિસ્સામાં, મુખ્ય પૃષ્ઠ પરની શોધ તમામ ઉત્પાદનો માટે કાર્ય કરે છે, અને જો તમે પહેલાથી જ કોઈ ચોક્કસ વિભાગમાં છો, તો પછી ફક્ત તેમાંના લેખો માટે.

સામગ્રી અને બ્રેડક્રમ્સમાં ઉમેરો. જ્યારે દરેક પૃષ્ઠમાં મેનૂ અને બ્રેડક્રમ્સ હોય ત્યારે તે સારું છે - કોઈપણ સ્તર પર પાછા ફરવાની ક્ષમતા સાથે વર્તમાન પૃષ્ઠ પર વપરાશકર્તાનો માર્ગ. જૂના ISP સિસ્ટમ દસ્તાવેજીકરણમાં, તમારે સામગ્રી મેળવવા માટે લેખમાંથી બહાર નીકળવું પડ્યું. તે અસુવિધાજનક હતું, તેથી અમે તેને નવામાં ઠીક કર્યું.

ઉત્પાદનમાં લિંક્સ મૂકો. જો લોકો એક જ પ્રશ્ન સાથે વારંવાર સમર્થન કરવા આવે છે, તો ઇન્ટરફેસમાં તેના ઉકેલ સાથે સંકેત ઉમેરવાનો અર્થ થાય છે. જો તમારી પાસે ડેટા અથવા સમજ હોય ​​કે જ્યારે કોઈ વપરાશકર્તા કોઈ સમસ્યા અનુભવી રહ્યો હોય, તો તમે તેમને મેઇલિંગ સૂચિ સાથે પણ સૂચિત કરી શકો છો. તેમને ચિંતા બતાવો અને આધાર પરથી બોજ દૂર કરો.

પોપ-અપ વિન્ડોમાં જમણી બાજુએ ISPmanager ના ડોમેન મેનેજમેન્ટ વિભાગમાં DNSSEC સેટ કરવા વિશેના લેખની લિંક છે

દસ્તાવેજીકરણમાં ક્રોસ-રેફરન્સ સેટ કરો. એકબીજા સાથે સંબંધિત લેખો "લિંક" હોવા જોઈએ. જો લેખો ક્રમિક છે, તો દરેક ટેક્સ્ટના અંતે આગળ અને પાછળના તીરો ઉમેરવાની ખાતરી કરો.

સંભવત,, કોઈ વ્યક્તિ પહેલા તેના પ્રશ્નનો જવાબ તમને નહીં, પરંતુ સર્ચ એન્જિન પર શોધશે. જો તકનીકી કારણોસર ત્યાં દસ્તાવેજોની કોઈ લિંક્સ ન હોય તો તે શરમજનક છે. તેથી સર્ચ એન્જિન ઓપ્ટિમાઇઝેશનનું ધ્યાન રાખો.

સમસ્યા 4. જૂનું લેઆઉટ ધારણામાં દખલ કરે છે

ખરાબ લખાણો ઉપરાંત, દસ્તાવેજીકરણ ડિઝાઇન દ્વારા બગાડી શકાય છે. લોકો સારી રીતે લખેલી સામગ્રી વાંચવા ટેવાયેલા છે. બ્લોગ્સ, સામાજિક નેટવર્ક્સ, મીડિયા - બધી સામગ્રી માત્ર સુંદર જ નહીં, પણ વાંચવામાં સરળ અને આંખને આનંદદાયક પણ રજૂ કરવામાં આવે છે. તેથી, તમે નીચે આપેલા સ્ક્રીનશોટની જેમ ટેક્સ્ટ જોનાર વ્યક્તિની પીડા સરળતાથી સમજી શકો છો.

આ લેખમાં ઘણા બધા સ્ક્રીનશૉટ્સ અને હાઇલાઇટ્સ છે કે તેઓ મદદ કરતા નથી, પરંતુ માત્ર ખ્યાલમાં દખલ કરે છે (ચિત્ર ક્લિક કરી શકાય તેવું છે)

તમારે અસરોના સમૂહ સાથે દસ્તાવેજીકરણમાંથી લાંબા વાંચન ન કરવું જોઈએ, પરંતુ તમારે મૂળભૂત નિયમો ધ્યાનમાં લેવાની જરૂર છે.

લેઆઉટ. મુખ્ય ટેક્સ્ટની પહોળાઈ, ફોન્ટ, કદ, હેડિંગ અને પેડિંગ નક્કી કરો. ડિઝાઇનરને હાયર કરો, અને કામ સ્વીકારવા અથવા તે જાતે કરવા માટે, આર્ટિઓમ ગોર્બુનોવનું પુસ્તક "ટાઇપોગ્રાફી અને લેઆઉટ" વાંચો. તે લેઆઉટનો માત્ર એક જ દૃશ્ય રજૂ કરે છે, પરંતુ તે તદ્દન પર્યાપ્ત છે.

ફાળવણી. ટેક્સ્ટમાં શું ભાર આપવાની જરૂર છે તે નક્કી કરો. સામાન્ય રીતે આ ઈન્ટરફેસ, બટનો, કોડ ઈન્સર્ટ, રૂપરેખાંકન ફાઈલો, “કૃપા કરીને નોંધ કરો” બ્લોક્સનો પાથ છે. આ તત્વોની ફાળવણી શું હશે તે નક્કી કરો અને તેને નિયમોમાં રેકોર્ડ કરો. ધ્યાનમાં રાખો કે ઓછું સ્રાવ, વધુ સારું. જ્યારે તેમાં ઘણા બધા હોય છે, ત્યારે ટેક્સ્ટ ઘોંઘાટીયા હોય છે. અવતરણ ચિહ્નો પણ ઘોંઘાટ પેદા કરે છે જો તેનો વારંવાર ઉપયોગ કરવામાં આવે.

સ્ક્રીનશોટ. ટીમ સાથે સંમત થાઓ કે કયા કિસ્સામાં સ્ક્રીનશોટની જરૂર છે. દરેક પગલાને સ્પષ્ટ કરવાની જરૂર નથી. મોટી સંખ્યામાં સ્ક્રીનશોટ, સહિત. અલગ બટનો, ધારણામાં દખલ કરે છે, લેઆઉટ બગાડે છે. સ્ક્રીનશોટ પરનું કદ, તેમજ હાઇલાઇટ્સ અને હસ્તાક્ષરોનું ફોર્મેટ નક્કી કરો અને તેને નિયમોમાં રેકોર્ડ કરો. યાદ રાખો કે ચિત્રો હંમેશા જે લખાયેલ છે તેને અનુરૂપ અને સુસંગત હોવા જોઈએ. ફરીથી, જો ઉત્પાદન નિયમિતપણે અપડેટ કરવામાં આવે છે, તો દરેકને ટ્રૅક રાખવું મુશ્કેલ બનશે.

ટેક્સ્ટ લંબાઈ. વધુ પડતા લાંબા લેખો ટાળો. તેમને ભાગોમાં તોડો, અને જો આ શક્ય ન હોય તો, લેખની શરૂઆતમાં એન્કર લિંક્સ સાથે સામગ્રી ઉમેરો. લેખને દૃષ્ટિની રીતે ટૂંકો બનાવવાનો એક સરળ રસ્તો એ છે કે વાચકોના સાંકડા વર્તુળ દ્વારા જરૂરી તકનીકી વિગતોને સ્પોઇલર હેઠળ છુપાવવી.

ફોર્મેટ્સ. તમારા લેખોમાં ઘણા ફોર્મેટ ભેગા કરો: ટેક્સ્ટ, વિડિયો અને છબીઓ. આ ધારણામાં સુધારો કરશે.

સુંદર લેઆઉટ સાથે સમસ્યાઓને ઢાંકવાનો પ્રયાસ કરશો નહીં. પ્રામાણિકપણે, અમે પોતે આશા રાખીએ છીએ કે "રૅપર" જૂના દસ્તાવેજોને સાચવશે - તે કામ કરતું નથી. ગ્રંથોમાં એટલો બધો દ્રશ્ય ઘોંઘાટ અને બિનજરૂરી વિગતો હતી કે નિયમો અને નવી ડિઝાઇન શક્તિહીન હતી.

ઉપરોક્ત મોટા ભાગનું તમે દસ્તાવેજીકરણ માટે ઉપયોગ કરો છો તે પ્લેટફોર્મ દ્વારા નક્કી કરવામાં આવશે. ઉદાહરણ તરીકે, અમારી પાસે સંગમ છે. મારે પણ તેની સાથે ટિંકર કરવું પડ્યું. જો રસ હોય, તો અમારા વેબ ડેવલપરની વાર્તા વાંચો: જાહેર જ્ઞાન આધાર માટે સંગમ: ડિઝાઇન બદલવી અને ભાષાઓ દ્વારા વિભાજન સેટ કરવું.

ક્યાંથી સુધરવાનું શરૂ કરવું અને કેવી રીતે ટકી રહેવું

જો તમારું દસ્તાવેજીકરણ ISPsystem જેટલું વિશાળ છે અને તમને ક્યાંથી શરૂઆત કરવી તે ખબર નથી, તો સૌથી મોટી સમસ્યાઓથી શરૂઆત કરો. ક્લાયન્ટ દસ્તાવેજને સમજી શકતા નથી - ગ્રંથોમાં સુધારો કરો, નિયમો બનાવો, લેખકોને તાલીમ આપો. દસ્તાવેજીકરણ જૂનું છે - આંતરિક પ્રક્રિયાઓની કાળજી લો. સૌથી વધુ લોકપ્રિય ઉત્પાદનો વિશેના સૌથી લોકપ્રિય લેખોથી પ્રારંભ કરો: સમર્થન માટે પૂછો, શોધ એન્જિનમાં સાઇટ વિશ્લેષણ અને પ્રશ્નો જુઓ.

ચાલો તરત જ કહીએ - તે સરળ રહેશે નહીં. અને તે ઝડપથી કામ કરે તેવી શક્યતા પણ નથી. જ્યાં સુધી તમે હમણાં જ શરૂઆત કરી રહ્યાં નથી અને તરત જ યોગ્ય વસ્તુ કરો. એક વસ્તુ જે આપણે નિશ્ચિતપણે જાણીએ છીએ તે એ છે કે તે સમય જતાં વધુ સારું થશે. પરંતુ પ્રક્રિયા ક્યારેય સમાપ્ત થશે નહીં :-).

સોર્સ: www.habr.com