编写文档是一种换位思考的练习。我们并不是在描述客观现实——源代码已经做到了。我们的工作是帮助塑造用户与 Vue 生态系统之间的关系。这份不断发展的指南提供了一些规则和建议,说明如何在 Vue 生态系统中始终如一地做到这一点。
#原则我们有一些专用的样式来表示需要以特定方式突出显示的内容。这些被捕获为在这个页面 (opens new window)请谨慎使用。
滥用这些样式是有一定诱惑力的,因为你可以简单地在标注中添加更改。但是,这会破坏用户的阅读流程,因此,只能在特殊情况下使用。在可能的情况下,我们应该尝试在页面内创建一个叙述和流程,以尊重读者的认知负荷。
在任何情况下都不应该相邻使用两个警告,这表明我们无法很好地解释上下文。
#贡献我们欣赏小型、集中的 PR。如果你想进行非常大的更改,请在发起请求之前与团队成员沟通。这是一份详细说明为什么这一点如此重要的书面材料 (opens new window)让我们在这个团队里工作得很好。请理解,尽管我们总是很感激你的贡献,但最终我们必须优先考虑哪些对整个项目最有效。
#资源#软件英文原文:
#VueDocsWritingGuide
Writingdocumentationisanexerciseinempathy.We'renotdescribinganobjectivereality-thesourcecodealreadydoesthat.OurjobistohelpshapetherelationshipbetweenusersandtheVueecosystem.Thisever-evolvingguideprovidessomerulesandrecommendationsonhowtodothatconsistentlywithintheVueecosystem.
##Principles
-**Afeaturedoesn'texistuntilit'swelldocumented.**
-**Respectusers'cognitivecapacity(i.e.brainpower).**Whenauserstartsreading,theybeginwithacertainamountoflimitedbrainpowerandwhentheyrunout,theystoplearning.
-Cognitivecapacityis**depletedfaster**bycomplexsentences,havingtolearnmorethanoneconceptatatime,andabstractexamplesthatdon'tdirectlyrelatetoauser'swork.
-Cognitivecapacityis**depletedmoreslowly**whenwehelpthemfeelconsistentlysmart,powerful,andcurious.Breakingthingsdownintodigestiblepiecesandmindingtheflowofthedocumentcanhelpkeeptheminthisstate.
-**Alwaystrytoseefromtheuser'sperspective.**Whenweunderstandsomethingthoroughly,itbecomesobvioustous.Thisiscalled_thecurseofknowledge_.Inordertowritegooddocumentation,trytorememberwhatyoufirstneededtoknowwhenlearningthisconcept.Whatjargondidyouneedtolearn?Whatdidyoumisunderstand?Whattookalongtimetoreallygrasp?Gooddocumentationmeetsuserswheretheyare.Itcanbehelpfultopracticeexplainingtheconcepttopeopleinpersonbefore
-**Describethe_problem_first,thenthesolution.**Beforeshowinghowafeatureworks,it'simportanttoexplainwhyitexists.Otherwise,userswon'thavethecontexttoknowifthisinformationisimportanttothem(isitaproblemtheyexperience?)orwhatpriorknowledge/experiencetoconnectitto.
-**Whilewriting,don'tbeafraidtoaskquestions**,_especially_ifyou'reafraidtheymightbe"dumb".Beingvulnerableishard,butit'stheonlywayforustomorefullyunderstandwhatweneedtoexplain.
-**Beinvolvedinfeaturediscussions.**ThebestAPIscomefromdocumentation-drivendevelopment,wherewebuildfeaturesthatareeasytoexplain,ratherthantryingtofigureouthowtoexplainthemlater.Askingquestions(especially"dumb"questions)earlieroftenhelpsrevealconfusions,inconsistencies,andproblematicbehaviorbeforeabreakingchangewouldberequiredtofixthem.
##Organization
-**Installation/Integration**:Provideathoroughoverviewofhowtointegratethesoftwareintoasmanydifferentkindsofprojectsasnecessary.
-**Introduction/GettingStarted**:
-Providealessthan10minuteoverviewoftheproblemstheprojectsolvesandwhyitexists.
-Providealessthan30minuteoverviewoftheproblemstheprojectsolvesandhow,includingwhenandwhytousetheprojectandsomesimplecodeexamples.Attheend,linktobothtoInstallationpageandthebeginningoftheEssentialsGuide.
-**Guide**:Makeusersfeelsmart,powerful,andcurious,thenmaintainthisstatesothatusersmaintainthemotivationandcognitivecapacitytokeeplearningmore.Guidepagesaremeanttobereadsequentially,soshouldgenerallybeorderedfromthehighesttolowestpower/effortratio.
-**Essentials**:Itshouldtakenolongerthan5hourstoreadtheEssentials,thoughshorterisbetter.Itsgoalistoprovidethe20%ofknowledgethatwillhelpusershandle80%ofusecases.EssentialscanlinktomoreadvancedguidesandtheAPI,though,inmostcases,youshouldavoidsuchlinks.Whentheyareprovided,youneedalsoprovideacontextsousersareawareiftheyshouldfollowthislinkontheirfirstreading.Otherwise,manyusersendupexhaustingtheircognitivecapacitylink-hopping,tryingtofullylearneveryaspectofafeaturebeforemovingon,andasaresult,neverfinishthatfirstread-throughoftheEssentials.Rememberthatasmoothreadismoreimportantthanbeingthorough.Wewanttogivepeopletheinformationtheyneedtoavoidafrustratingexperience,buttheycanalwayscomebackandreadfurther,orGooglealesscommonproblemwhentheyencounterit.
-**Advanced**:WhiletheEssentialshelpspeoplehandle~80%ofusecases,subsequentguideshelpgetusersto95%ofusecases,plusmoredetailedinformationonnon-essentialfeatures(e.g.transitions,animations),morecomplexconveniencefeatures(e.g.mixins,customdirectives),anddevexperienceimprovements(e.g.JSX,plugins).Thefinal5%ofusecasesthataremoreniche,complex,and/orpronetoabusewillbelefttothecookbookandAPIreference,whichcanbelinkedtofromtheseadvancedguides.
-**Reference/API**:Provideacompletelistoffeatures,includingtypeinformation,descriptionsoftheproblemeachsolves,examplesofeverycombinationofoptions,andlinkstoguides,cookbookrecipes,andotherinternalresourcesprovidingmoredetail.Unlikeotherpages,thisoneisnotmeanttobereadtop-to-bottom,soplentyofdetailcanbeprovided.Thesereferencesmustalsobemoreeasilyskimmablethantheguides,sotheformatshouldbeclosertodictionaryentriesthanthestory-tellingformatoftheguides.
-**Migrations**:
-**Versions**:Whenimportantchangesaremade,it'susefultoincludeafulllistofchanges,includingadetailedexplanationofwhythechangewasmadeandhowtomigratetheirprojects.
-**Fromotherprojects**:Howdoesthissoftwarecomparetosimilarsoftware?Thisisimportanttohelpusersunderstandwhatadditionalproblemswemightsolveorcreateforthem,andtowhatextenttheycantransferknowledgetheyalreadyhave.
-**StyleGuide**:Therearenecessarilysomekeypiecesindevelopmentthatneedadecision,butarenotcoretotheAPI.Thestyleguideprovideseducated,opinionatedrecommendationstohelpguidethesedecisions.Theyshouldn'tbefollowedblindly,butcanhelpteamssavetimebybeingalignedonsmallerdetails.
-**Cookbook**:RecipesinthecookbookarewrittenwithsomeassumptionoffamiliaritywithVueanditsecosystem.EachisahighlystructureddocumentthatwalksthroughsomecommonimplementationdetailsthataVuedevmightencounter.
##Writing&Grammar
###Style
-**Headingsshoulddescribeproblems**,notsolutions.Forexample,alesseffectiveheadingmightbe"Usingprops",becauseitdescribesasolution.Abetterheadingmightbe"PassingDatatoChildComponentswithProps",becauseitprovidesthecontextoftheproblempropssolve.Userswon'treallystartpayingattentiontotheexplanationofafeatureuntiltheyhavesomeideaofwhy/whenthey'duseit.
-**Whenyouassumeknowledge,declareit**atthebeginningandlinktoresourcesforlesscommonknowledgethatyou'reexpecting.
-**Introduceonlyonenewconceptatatimewheneverpossible**(includingbothtextandcodeexamples).Evenifmanypeopleareabletounderstandwhenyouintroducemorethanone,therearealsomanywhowillbecomelost-andeventhosewhodon'tbecomelostwillhavedepletedmoreoftheircognitivecapacity.
-**Avoidspecialcontentblocksfortipsandcaveatswhenpossible.**It'sgenerallypreferabletoblendthesemorenaturallyintothemaincontent,e.g.bybuildingonexamplestodemonstrateanedgecase.
-**Don'tincludemorethantwointerwoventipsandcaveatsperpage.**Ifyoufindthatmorethantwotipsareneededinapage,consideraddingacaveatssectiontoaddresstheseissues.Theguideismeanttobereadstraightthrough,andtipsandcaveatscanbeoverwhelmingordistractingtosomeonetryingtounderstandthebaseconcepts.
-**Avoidappealstoauthority**(e.g."youshoulddoX,becausethat'sabestpractice"or"Xisbestbecauseitgivesyoufullseparationofconcerns").Instead,demonstratewithexamplesthespecifichumanproblemscausedand/orsolvedbyapattern.
-**Whendecidingwhattoteachfirst,thinkofwhatknowledgewillprovidethebestpower/effortratio.**Thatmeansteachingwhateverwillhelpuserssolvethegreatestpainsorgreatestnumberofproblems,withtherelativelyleastefforttolearn.Thishelpslearnersfeelsmart,powerful,andcurious,sotheircognitivecapacitywilldrainmoreslowly.
-**Unlessthecontextassumesastringtemplateorbuildsystem,onlywritecodethatworksinanyenvironmentbythesoftware(e.g.Vue,Vuex,etc).**
-**Show,don'ttell.**Forexample,"TouseVueonapage,youcanaddthistoyourHTML"(thenshowthescripttag),insteadof"TouseVueonapage,youcanaddascriptelementwithasrcattribute,thevalueofwhichshouldbealinktoVue'scompiledsource".
-**Almostalwaysavoidhumor(forEnglishdocs)**,especiallysarcasmandpopculturereferences,asitdoesn'ttranslatewellacrosscultures.
-**Neverassumeamoreadvancedcontextthanyouhaveto.**
-**Inmostcases,preferlinksbetweensectionsofthedocsoverrepeatingthesamecontentinmultiplesections.**Somerepetitionincontentisunavoidableandevenessentialforlearning.However,toomuchrepetitionalsomakesthedocsmoredifficulttomaintain,becauseachangeintheAPIwillrequirechangesinmanyplacesandit'seasytomisssomething.Thisisadifficultbalancetostrike.
-**Specificisbetterthangeneric.**Forexample,a`<BlogPost>`componentexampleisbetterthan`<ComponentA>`.
-**Relatableisbetterthanobscure.**Forexample,a`<BlogPost>`componentexampleisbetterthan`<CurrencyExchangeSettings>`.
-**Beemotionallyrelevant.**Explanationsandexamplesthatrelatetosomethingpeoplehaveexperiencewithandcareaboutwillalwaysbemoreeffective.
-**Alwaysprefersimpler,plainerlanguageovercomplexorjargonylanguage.**Forexample:
-"youcanuseVuewithascriptelement"insteadof"inordertoinitiatetheusageofVue,onepossibleoptionistoactuallyinjectitviaascriptHTMLelement"
-"functionthatreturnsafunction"insteadof"higherorderfunction"
-**Avoidlanguagethatinvalidatestruggle**,suchas"easy","just","obviously",etc.Forreference,see[WordsToAvoidinEducationalWriting](https://css-tricks.com/words-avoid-educational-writing/).
###Grammar
-**Avoidabbreviations**inwritingandcodeexamples(e.g.`attribute`isbetterthan`attr`,`message`isbetterthan`msg`),unlessyouarespecificallyreferencinganabbreviationinanAPI(e.g.`$attrs`).Abbreviationsymbolsincludedonstandardkeyboards(e.g.`@`,`#`,`&`)areOK.
-**Whenreferencingadirectlyfollowingexample,useacolon(`:`)toendasentence**,ratherthanaperiod(`.`).
-**UsetheOxfordcomma**(e.g."a,b,andc"insteadof"a,bandc").![WhytheOxfordcommaisimportant](https://raw.githubusercontent.com/vuejs/vuejs.org/master/src/images/oxford-comma.jpg)
-**Whenreferencingthenameofaproject,prioritizethebroaderconventionsofEnglishoverinternalbrandingconventionsofthatproject.**Forexample,"webpack"and"npm"bothdisregardconventionssuchas"alwaysstartawordatthebeginningofasentencewithacapitalletter","projectnamesalwaysuseTitleCase",and"acronymsarealwayscapitalized".Instead,alwayswrite"WebpackandNPM"toprovideamoreconsistentexperienceinthedocsandavoidsentenceslike"Ifyoudon'twanttouseVueCLI,youcanusewebpackorRollupdirectlybyinstallingthemvianpmorYarn".
-**UseTitleCaseforheadings**-atleastfornow,sinceit'swhatweusethroughtherestofthedocs.There'sresearchsuggestingthatsentencecase(onlyfirstwordoftheheadingstartswithacapital)isactuallysuperiorforlegibilityandalsoreducesthecognitiveoverheadfordocumentationwriters,sincetheydon'thavetotrytorememberwhethertocapitalizewordslike"and","with",and"about".
-**Don'tuseemojis(exceptindiscussions).**Emojisarecuteandfriendly,buttheycanbeadistractionindocumentationandsomeemojievenconveydifferentmeaningsindifferentcultures.
##Iteration&Communication
-**Excellencecomesfromiteration.**Firstdraftsarealwaysbad,butwritingthemisavitalpartoftheprocess.It'sextremelydifficulttoavoidtheslowprogressionofBad->OK->Good->Great->Inspiring->Transcendent.
-**Onlywaituntilsomethingis"Good"beforepublishing.**Thecommunitywillhelpyoupushitfurtherdownthechain.
-**Trynottogetdefensivewhenreceivingfeedback.**Ourwritingcanbeverypersonaltous,butifwegetupsetwiththepeoplewhohelpusmakeitbetter,theywilleitherstopgivingfeedbackorstartlimitingthekindoffeedbacktheygive.
-**Proof-readyourownworkbeforeshowingittoothers.**Ifyoushowsomeoneworkwithalotofspelling/grammarmistakes,you'llgetfeedbackaboutspellinggrammar/mistakesinsteadofmorevaluablenotesaboutwhetherthewritingisachievingyourgoals.
-**Whenyouaskpeopleforfeedback,tellreviewerswhat:**
-**you'retryingtodo**
-**yourfearsare**
-**balancesyou'retryingtostrike**
-**Whensomeonereportsaproblem,thereisalmostalwaysaproblem**,evenifthesolutiontheyproposedisn'tquiteright.Keepaskingfollow-upquestionstolearnmore.
-Peopleneedtofeelsafeaskingquestionswhencontributing/reviewingcontent.Here'showyoucandothat:
-**Thankpeoplefortheircontributions/reviews,evenifyou'refeelinggrumpy.**Forexample:
-"Greatquestion!"
-"Thanksfortakingthetimetoexplain."
-"Thisisactuallyintentional,butthanksfortakingthetimetocontribute."
-**Listentowhatpeoplearesayingandmirrorifyou'renotsureyou'reunderstandingcorrectly.**Thiscanhelpvalidatepeople'sfeelingsandexperiences,whilealsounderstandingif*you're*understanding*them*correctly.
-**Usealotofpositiveandempatheticemojis.**It'salwaysbettertoseemalittlestrangethanmeanorimpatient.
-**Kindlycommunicaterules/boundaries.**Ifsomeonebehavesinawaythat'sabusive/inappropriate,respondonlywithkindnessandmaturity,butalsomakeitclearthatthisbehaviorisnotacceptableandwhatwillhappen(accordingtothecodeofconduct)iftheycontinuebehavingpoorly.
##Resources
###Software
-[Grammarly](https://www.grammarly.com/):Desktopappandbrowserextensionforcheckingspellingandgrammar(thoughgrammarcheckingdoesn'tcatcheverythingandoccasionallyshowsafalsepositive).
-[CodeSpellChecker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker):AnextensionforVSCodetohelpyoucheckspellingwithinmarkdownandcodeexamples.
###Books
-[OnWritingWell](https://www.amazon.com/Writing-Well-30th-Anniversary-Nonfiction-ebook/dp/B0090RVGW0)(see[popularquotes](https://www.goodreads.com/work/quotes/1139032-on-writing-well-the-classic-guide-to-writing-nonfiction))
-[BirdbyBird](https://www.amazon.com/Bird-Some-Instructions-Writing-Life/dp/0385480016)(see[popularquotes](https://www.goodreads.com/work/quotes/841198-bird-by-bird-some-instructions-on-writing-and-life))
-[CognitiveLoadTheory](https://www.amazon.com/Cognitive-Explorations-Instructional-Performance-Technologies/dp/144198125X/)
,
Copyright © 2008-2022 秒下下载站
m.down10s.com .All Rights Reserved