సాఫ్ట్‌వేర్ డాక్యుమెంటేషన్ కేవలం కథనాల సమితి. కానీ అవి కూడా మిమ్మల్ని వెర్రివాడిగా మార్చగలవు. మొదట, మీరు అవసరమైన సూచనల కోసం చాలా కాలం వెతుకుతున్నారు. అప్పుడు మీరు అస్పష్టమైన వచనాన్ని అర్థం చేసుకుంటారు. మీరు వ్రాసినట్లు చేస్తారు, కానీ సమస్య పరిష్కారం కాలేదు. మీరు మరొక కథనం కోసం వెతుకుతారు, మీరు ఉద్విగ్నత చెందుతారు ... ఒక గంట తర్వాత మీరు ప్రతిదీ వదులుకుని వెళ్లిపోతారు. ఈ విధంగా చెడ్డ డాక్యుమెంటేషన్ పని చేస్తుంది. ఇది ఇలా చేస్తుంది మరియు దాన్ని ఎలా పరిష్కరించాలి - కట్ కింద చదవండి.
మా పాత డాక్యుమెంటేషన్‌లో చాలా లోపాలు ఉన్నాయి. పైన వివరించిన దృశ్యం మా క్లయింట్‌లను ప్రభావితం చేయని విధంగా మేము ఇప్పుడు దాదాపు ఒక సంవత్సరం పాటు దీన్ని మళ్లీ పని చేస్తున్నాము. చూడు, и .
సమస్య 1: అస్పష్టంగా, పేలవంగా వ్రాసిన కథనాలు
డాక్యుమెంటేషన్ అర్థం చేసుకోవడం అసాధ్యం అయితే, దాని ప్రయోజనం ఏమిటి? కానీ ఎవరూ ఉద్దేశపూర్వకంగా అర్థంకాని కథనాలు రాయరు. రచయిత ప్రేక్షకులు మరియు ప్రయోజనం గురించి ఆలోచించనప్పుడు, నీటిని పోయడం మరియు లోపాల కోసం వచనాన్ని తనిఖీ చేయనప్పుడు అవి జరుగుతాయి.
- ప్రేక్షకులు. ఒక కథనాన్ని వ్రాసే ముందు, మీరు పాఠకుల తయారీ స్థాయి గురించి ఆలోచించాలి. అనుభవశూన్యుడు కోసం ఒక కథనంలో మీరు ప్రాథమిక దశలను దాటవేయకూడదు మరియు వివరణ లేకుండా సాంకేతిక పదాలను వదిలివేయకూడదు, కానీ నిపుణులకు మాత్రమే అవసరమైన అరుదైన ఫీచర్‌పై వ్యాసంలో, మీరు PHP అనే పదం యొక్క అర్ధాన్ని వివరించాలి.
- లక్ష్యం. ఇంకో విషయం ముందుగా ఆలోచించాలి. రచయిత స్పష్టమైన లక్ష్యాన్ని నిర్దేశించుకోవాలి, వ్యాసం యొక్క ఉపయోగకరమైన ప్రభావాన్ని నిర్ణయించాలి మరియు దానిని చదివిన తర్వాత రీడర్ ఏమి చేయాలో నిర్ణయించుకోవాలి. ఇది చేయకపోతే, మీరు వివరణ కోసం వివరణతో ముగుస్తుంది.
- నీరు మరియు దోషాలు. చాలా అనవసరమైన సమాచారం ఉంది మరియు బ్యూరోక్రసీ, లోపాలు మరియు అక్షరదోషాలు అవగాహనకు ఆటంకం కలిగిస్తాయి. పాఠకుడు వ్యాకరణ నాజీ కాకపోయినా, వచనంలో అజాగ్రత్త అతనిని ఆఫ్ చేస్తుంది.
పై చిట్కాలను పరిగణించండి మరియు కథనాలు మరింత స్పష్టంగా కనిపిస్తాయి - హామీ ఇవ్వబడుతుంది. దీన్ని మరింత మెరుగుపరచడానికి, మా ఉపయోగించండి .
సమస్య 2. కథనాలు అన్ని ప్రశ్నలకు సమాధానం ఇవ్వవు
డాక్యుమెంటేషన్ అభివృద్ధిని కొనసాగించనప్పుడు ఇది చెడ్డది, నిజమైన ప్రశ్నలకు సమాధానం ఇవ్వదు మరియు దానిలోని లోపాలు సంవత్సరాలుగా సరిదిద్దబడవు. ఇవి రచయిత యొక్క చాలా సమస్యలు కాదు, కానీ సంస్థలోని ప్రక్రియల సంస్థ.
డాక్యుమెంటేషన్ అభివృద్ధికి అనుగుణంగా లేదు
ఫీచర్ ఇప్పటికే విడుదలలో ఉంది, దానిని కవర్ చేయడానికి మార్కెటింగ్ ప్లాన్ చేస్తోంది, ఆపై కొత్త కథనం లేదా అనువాదం ఇప్పటికీ డాక్యుమెంటేషన్‌లో లేదని తేలింది. దీంతో విడుదలను కూడా వాయిదా వేయాల్సి వచ్చింది. మీకు కావలసినంత సమయానికి సాంకేతిక రచయితలకు పనులను అప్పగించమని మీరు ప్రతి ఒక్కరినీ అడగవచ్చు, కానీ అది పని చేయదు. ప్రక్రియ స్వయంచాలకంగా లేకపోతే, పరిస్థితి పునరావృతమవుతుంది.
మేము YouTrackకి మార్పులు చేసాము. ఫీచర్ పరీక్షించడం ప్రారంభించిన అదే క్షణంలో కొత్త ఫీచర్ గురించి కథనాన్ని వ్రాసే పని సాంకేతిక రచయితకు వస్తుంది. ప్రమోషన్ కోసం సిద్ధం కావడానికి మార్కెటింగ్ దాని గురించి తెలుసుకుంటుంది. నోటిఫికేషన్‌లు మ్యాటర్‌మోస్ట్ కార్పొరేట్ మెసెంజర్‌లో కూడా వస్తాయి, కాబట్టి డెవలపర్‌ల నుండి వార్తలను కోల్పోవడం అసాధ్యం.
డాక్యుమెంటేషన్ వినియోగదారు అభ్యర్థనలను ప్రతిబింబించదు
మేము ఇలా పనిచేయడం అలవాటు చేసుకున్నాము: ఒక లక్షణం వచ్చింది, మేము దాని గురించి మాట్లాడాము. దీన్ని ఎలా ఆన్ చేయాలో, ఆఫ్ చేయాలో మరియు చక్కటి సర్దుబాట్లు ఎలా చేయాలో మేము వివరించాము. అయితే ఒక క్లయింట్ మన సాఫ్ట్‌వేర్‌ను మనం ఊహించని విధంగా ఉపయోగిస్తే? లేక మనం ఆలోచించని లోపాలు ఇందులో ఉన్నాయా?
డాక్యుమెంటేషన్ సాధ్యమైనంత వరకు పూర్తయిందని నిర్ధారించుకోవడానికి, మేము మద్దతు అభ్యర్థనలను, నేపథ్య ఫోరమ్‌లలోని ప్రశ్నలు మరియు శోధన ఇంజిన్‌లలోని ప్రశ్నలను విశ్లేషించమని సిఫార్సు చేస్తున్నాము. అత్యంత ప్రజాదరణ పొందిన అంశాలు సాంకేతిక రచయితలకు బదిలీ చేయబడతాయి, తద్వారా వారు ఇప్పటికే ఉన్న కథనాలను భర్తీ చేయవచ్చు లేదా కొత్త వాటిని వ్రాయవచ్చు.
డాక్యుమెంటేషన్ మెరుగుపరచబడటం లేదు
దీన్ని వెంటనే పూర్తి చేయడం కష్టం; ఇంకా తప్పులు ఉంటాయి. మీరు కస్టమర్‌ల నుండి ఫీడ్‌బ్యాక్ కోసం ఆశించవచ్చు, కానీ వారు ప్రతి అక్షర దోషం, సరికాని, అపారమయిన లేదా నిరాధారమైన కథనాన్ని నివేదించే అవకాశం లేదు. క్లయింట్‌లతో పాటు, ఉద్యోగులు డాక్యుమెంటేషన్‌ను చదువుతారు, అంటే వారు అదే లోపాలను చూస్తారు. ఇది ఉపయోగించవచ్చు! మీరు సమస్యను సులభంగా నివేదించే పరిస్థితులను సృష్టించాలి.
డాక్యుమెంటేషన్‌పై ఉద్యోగులు వ్యాఖ్యలు, సూచనలు మరియు ఆలోచనలను అందించే అంతర్గత పోర్టల్‌లో మాకు ఒక సమూహం ఉంది. మద్దతుకు కథనం అవసరమా, కానీ అది ఉనికిలో లేదా? పరీక్షకుడు సరికాని విషయాన్ని గమనించారా? లోపాల గురించి భాగస్వామి డెవలప్‌మెంట్ మేనేజర్‌లకు ఫిర్యాదు చేశారా? ఈ గుంపులో అందరూ! సాంకేతిక రచయితలు కొన్ని విషయాలను వెంటనే పరిష్కరిస్తారు, కొన్ని విషయాలను YouTrackకి బదిలీ చేస్తారు మరియు ఇతరులకు ఆలోచించడానికి కొంత సమయం ఇస్తారు. టాపిక్ చనిపోకుండా నిరోధించడానికి, మేము ఎప్పటికప్పుడు సమూహం యొక్క ఉనికిని మరియు అభిప్రాయం యొక్క ప్రాముఖ్యతను మీకు గుర్తు చేస్తాము.
సమస్య 3. సరైన కథనాన్ని కనుగొనడానికి చాలా సమయం పడుతుంది.
దొరకని వ్యాసం కంటే దొరకని వ్యాసం గొప్పది కాదు. మంచి డాక్యుమెంటేషన్ యొక్క నినాదం "శోధించడం సులభం, కనుగొనడం సులభం" అని ఉండాలి. దీన్ని ఎలా సాధించాలి?
నిర్మాణాన్ని నిర్వహించండి మరియు అంశాలను ఎంచుకోవడానికి సూత్రాన్ని నిర్ణయించండి. “ఈ కథనాన్ని నేను ఎక్కడ కనుగొనగలను?” అని పాఠకుడు ఆలోచించకుండా నిర్మాణం వీలైనంత పారదర్శకంగా ఉండాలి. సంగ్రహంగా చెప్పాలంటే, రెండు విధానాలు ఉన్నాయి: ఇంటర్ఫేస్ నుండి మరియు టాస్క్‌ల నుండి.
- ఇంటర్ఫేస్ నుండి. కంటెంట్ ప్యానెల్ విభాగాలను నకిలీ చేస్తుంది. పాత ISP సిస్టమ్ డాక్యుమెంటేషన్‌లో ఇది జరిగింది.
- పనుల నుండి. కథనాలు మరియు విభాగాల శీర్షికలు వినియోగదారుల పనులను ప్రతిబింబిస్తాయి; శీర్షికలు దాదాపు ఎల్లప్పుడూ "ఎలా చేయాలి" అనే ప్రశ్నకు క్రియలు మరియు సమాధానాలను కలిగి ఉంటాయి. ఇప్పుడు మేము ఈ ఫార్మాట్‌కి వెళ్తున్నాము.
మీరు ఏ విధానాన్ని ఎంచుకున్నా, వినియోగదారులు వెతుకుతున్న దానికి సంబంధించిన అంశం మరియు వినియోగదారు ప్రశ్నను ప్రత్యేకంగా పరిష్కరించే విధంగా కవర్ చేయబడిందని నిర్ధారించుకోండి.
కేంద్రీకృత శోధనను సెటప్ చేయండి. ఆదర్శవంతమైన ప్రపంచంలో, మీరు భాషలో తప్పుగా వ్రాసినా లేదా పొరపాటు చేసినా కూడా శోధన పని చేస్తుంది. ఇంతవరకు సంగమంలోని మా శోధన దీనితో మమ్మల్ని సంతోషపెట్టలేదు. మీరు అనేక ఉత్పత్తులను కలిగి ఉంటే మరియు డాక్యుమెంటేషన్ సాధారణమైనట్లయితే, వినియోగదారు ఉన్న పేజీకి అనుగుణంగా శోధనను రూపొందించండి. మా విషయంలో, ప్రధాన పేజీలోని శోధన అన్ని ఉత్పత్తులకు పని చేస్తుంది మరియు మీరు ఇప్పటికే ఒక నిర్దిష్ట విభాగంలో ఉన్నట్లయితే, దానిలోని కథనాల కోసం మాత్రమే.
కంటెంట్ మరియు బ్రెడ్‌క్రంబ్‌లను జోడించండి. ప్రతి పేజీ మెనూ మరియు బ్రెడ్‌క్రంబ్‌లను కలిగి ఉన్నప్పుడు ఇది మంచిది - ఏ స్థాయికి అయినా తిరిగి వచ్చే సామర్థ్యంతో ప్రస్తుత పేజీకి వినియోగదారు మార్గం. పాత ISPసిస్టమ్ డాక్యుమెంటేషన్‌లో, మీరు కంటెంట్‌ను పొందడానికి కథనం నుండి నిష్క్రమించాలి. ఇది అసౌకర్యంగా ఉంది, కాబట్టి మేము దానిని కొత్తదానిలో పరిష్కరించాము.
ఉత్పత్తిలో లింక్‌లను ఉంచండి. ప్రజలు ఒకే ప్రశ్నతో పదే పదే మద్దతునిస్తే, ఇంటర్‌ఫేస్‌కు దాని పరిష్కారంతో సూచనను జోడించడం అర్ధమే. వినియోగదారు సమస్యను ఎదుర్కొంటున్నప్పుడు మీకు డేటా లేదా అంతర్దృష్టి ఉంటే, మీరు వారికి మెయిలింగ్ జాబితాతో కూడా తెలియజేయవచ్చు. వారికి శ్రద్ధ చూపండి మరియు మద్దతు నుండి భారాన్ని తీసివేయండి.
పాప్-అప్ విండోలో కుడి వైపున ISPmanager యొక్క డొమైన్ మేనేజ్‌మెంట్ విభాగంలో DNSSECని సెటప్ చేయడం గురించిన కథనానికి లింక్ ఉంది.
డాక్యుమెంటేషన్‌లో క్రాస్-రిఫరెన్స్‌లను సెటప్ చేయండి. ఒకదానికొకటి సంబంధించిన కథనాలను "లింక్" చేయాలి. కథనాలు వరుసగా ఉంటే, ప్రతి వచనం చివరిలో ముందుకు మరియు వెనుకకు బాణాలను జోడించాలని నిర్ధారించుకోండి.
చాలా మటుకు, ఒక వ్యక్తి మొదట తన ప్రశ్నకు సమాధానం కోసం వెతుకుతాడు మీకు కాదు, శోధన ఇంజిన్‌కు. సాంకేతిక కారణాల వల్ల డాక్యుమెంటేషన్‌కు లింక్‌లు లేకుంటే అది సిగ్గుచేటు. కాబట్టి సెర్చ్ ఇంజన్ ఆప్టిమైజేషన్‌ను జాగ్రత్తగా చూసుకోండి.
సమస్య 4. పాత లేఅవుట్ అవగాహనతో జోక్యం చేసుకుంటుంది
చెడు పాఠాలతో పాటు, డాక్యుమెంటేషన్ డిజైన్ ద్వారా చెడిపోవచ్చు. ప్రజలు బాగా వ్రాసిన విషయాలను చదవడం అలవాటు చేసుకున్నారు. బ్లాగులు, సోషల్ నెట్‌వర్క్‌లు, మీడియా - మొత్తం కంటెంట్ అందంగా మాత్రమే కాకుండా చదవడానికి సులభంగా మరియు కంటికి ఆహ్లాదకరంగా ఉంటుంది. అందువల్ల, దిగువ స్క్రీన్‌షాట్‌లో వచనాన్ని చూసే వ్యక్తి యొక్క బాధను మీరు సులభంగా అర్థం చేసుకోవచ్చు.
ఈ కథనంలో చాలా స్క్రీన్‌షాట్‌లు మరియు ముఖ్యాంశాలు ఉన్నాయి, అవి సహాయం చేయవు, కానీ అవగాహనకు మాత్రమే ఆటంకం కలిగిస్తాయి (చిత్రం క్లిక్ చేయదగినది)
మీరు అనేక ప్రభావాలతో డాక్యుమెంటేషన్ నుండి దీర్ఘకాలం చదవకూడదు, కానీ మీరు ప్రాథమిక నియమాలను పరిగణనలోకి తీసుకోవాలి.
లేఅవుట్. బాడీ టెక్స్ట్ వెడల్పు, ఫాంట్, సైజు, హెడ్డింగ్‌లు మరియు పాడింగ్‌ను నిర్ణయించండి. డిజైనర్‌ను నియమించుకోండి మరియు పనిని అంగీకరించడానికి లేదా మీరే చేయడానికి, ఆర్టియోమ్ గోర్బునోవ్ పుస్తకం "టైపోగ్రఫీ మరియు లేఅవుట్" చదవండి. ఇది లేఅవుట్ యొక్క ఒక వీక్షణను మాత్రమే అందిస్తుంది, కానీ ఇది చాలా సరిపోతుంది.
కేటాయింపులు. వచనంలో దేనికి ప్రాధాన్యత ఇవ్వాలో నిర్ణయించండి. సాధారణంగా ఇది ఇంటర్ఫేస్, బటన్లు, కోడ్ ఇన్సర్ట్‌లు, కాన్ఫిగరేషన్ ఫైల్‌లు, "దయచేసి గమనించండి" బ్లాక్‌లలో ఒక మార్గం. ఈ మూలకాల కేటాయింపులు ఏమిటో నిర్ణయించండి మరియు వాటిని నిబంధనలలో నమోదు చేయండి. తక్కువ ఉత్సర్గ, మంచిదని గుర్తుంచుకోండి. అవి చాలా ఉన్నప్పుడు, వచనం ధ్వనించేది. కొటేషన్ గుర్తులు కూడా చాలా తరచుగా ఉపయోగించినట్లయితే శబ్దాన్ని సృష్టిస్తాయి.
స్క్రీన్‌షాట్‌లు. ఏ సందర్భాలలో స్క్రీన్‌షాట్‌లు అవసరమో బృందంతో ఏకీభవించండి. ప్రతి అడుగును ఖచ్చితంగా వివరించాల్సిన అవసరం లేదు. పెద్ద సంఖ్యలో స్క్రీన్‌షాట్‌లు, సహా. ప్రత్యేక బటన్లు, అవగాహన జోక్యం, లేఅవుట్ పాడు. స్క్రీన్‌షాట్‌లపై పరిమాణాన్ని, అలాగే హైలైట్‌లు మరియు సంతకాల ఆకృతిని నిర్ణయించండి మరియు వాటిని నిబంధనలలో రికార్డ్ చేయండి. దృష్టాంతాలు ఎల్లప్పుడూ వ్రాసిన వాటికి అనుగుణంగా ఉండాలని మరియు సంబంధితంగా ఉండాలని గుర్తుంచుకోండి. మళ్ళీ, ఉత్పత్తిని క్రమం తప్పకుండా నవీకరించినట్లయితే, ప్రతి ఒక్కరినీ ట్రాక్ చేయడం కష్టం.
టెక్స్ట్ పొడవు. ఎక్కువ పొడవైన కథనాలను నివారించండి. వాటిని భాగాలుగా విభజించి, ఇది సాధ్యం కాకపోతే, వ్యాసం ప్రారంభంలో యాంకర్ లింక్‌లతో కంటెంట్‌ను జోడించండి. కథనాన్ని దృశ్యమానంగా చిన్నదిగా చేయడానికి సులభమైన మార్గం ఏమిటంటే, పాఠకుల ఇరుకైన సర్కిల్‌కు అవసరమైన సాంకేతిక వివరాలను స్పాయిలర్ కింద దాచడం.
ఆకృతులు. మీ కథనాలలో అనేక ఫార్మాట్‌లను కలపండి: వచనం, వీడియో మరియు చిత్రాలు. ఇది అవగాహనను మెరుగుపరుస్తుంది.
అందమైన లేఅవుట్‌తో సమస్యలను కప్పిపుచ్చడానికి ప్రయత్నించవద్దు. నిజాయితీగా, "రేపర్" పాత డాక్యుమెంటేషన్‌ను సేవ్ చేస్తుందని మేము ఆశించాము - అది పని చేయలేదు. గ్రంథాలలో చాలా దృశ్య శబ్దం మరియు అనవసరమైన వివరాలు ఉన్నాయి, నిబంధనలు మరియు కొత్త డిజైన్ శక్తిలేనివి.
మీరు డాక్యుమెంటేషన్ కోసం ఉపయోగించే ప్లాట్‌ఫారమ్ ద్వారా పైన పేర్కొన్న వాటిలో చాలా వరకు నిర్ణయించబడతాయి. ఉదాహరణకు, మనకు సంగమం ఉంది. నేను కూడా అతనితో టింకర్ చేయాల్సి వచ్చింది. ఆసక్తి ఉంటే, మా వెబ్ డెవలపర్ కథనాన్ని చదవండి: .
మెరుగుపరచడం ఎక్కడ ప్రారంభించాలి మరియు ఎలా జీవించాలి
మీ డాక్యుమెంటేషన్ ISP సిస్టమ్‌ల వలె విస్తృతంగా ఉంటే మరియు ఎక్కడ ప్రారంభించాలో మీకు తెలియకపోతే, అతిపెద్ద సమస్యలతో ప్రారంభించండి. క్లయింట్‌లు పత్రాన్ని అర్థం చేసుకోలేరు - పాఠాలను మెరుగుపరచండి, నిబంధనలను రూపొందించండి, రైటర్‌లకు శిక్షణ ఇవ్వండి. డాక్యుమెంటేషన్ గడువు ముగిసింది - అంతర్గత ప్రక్రియలను జాగ్రత్తగా చూసుకోండి. అత్యంత జనాదరణ పొందిన ఉత్పత్తుల గురించి అత్యంత జనాదరణ పొందిన కథనాలతో ప్రారంభించండి: మద్దతుని అడగండి, శోధన ఇంజిన్‌లలో సైట్ విశ్లేషణలు మరియు ప్రశ్నలను చూడండి.
వెంటనే చెప్పండి - ఇది సులభం కాదు. మరియు అది త్వరగా పని చేసే అవకాశం లేదు. మీరు ఇప్పుడే ప్రారంభించి, వెంటనే సరైన పని చేస్తే తప్ప. కాలక్రమేణా అది మెరుగుపడుతుందని మనకు ఖచ్చితంగా తెలుసు. కానీ ప్రక్రియ ఎప్పటికీ ముగియదు :-).
మూలం: www.habr.com