Good documentation - the YouTube Data API - LinkedIn

The primary Reference page provided a brief overview of the API. YouTube Data API Reference page screenshot. Later down the page, ... Recently,IwantedtogetsomeinformationaboutafewYouTubechannelsandendedupexploringtheYouTubeDataAPI.Iexpectedthelearningcurve,butitwasmademucheasierbythequalityofdocumentation.TheprimaryReferencepageprovidedabriefoverviewoftheAPI.Laterdownthepage,therewasalistofallthedifferentresourceswithanoverviewforeach.Thedocumentationwasfilledwithhyperlinks-referencestodetailedpageswithmoreinformationordetailswithinthesamepage.Unrelatedtodocumentation-AlltheAPImethodreferencepageshadasidepaneltoactuallyinvokethatAPIandchecktheresponse.IwasactuallytryingtoinvokethisAPIfromGoogleSheets. TherewasapagetogetstartedtousetheAPIinGoogleAppsScript,withadditionalcodesamplesalsoavailable.Insummary,alotofthoughtseemstohavegoneintohowthedocumentationwasstructured,keepingnoviceusersandexperienceddevelopersinmind.InowseethattheAPIdocumentationhasbeenmaintainedforaroundadecade.Thewritingisalsoveryclean,withouttoomuchjargon.Alotofquestionsonhowthisisalldone.Arethesewrittenbydevelopers?Or,dotheyhaveseparatetechnicalwriters?Isthisplannedoutinadvance?Or,isthiswrittenoutinpiecesandorganizedattheend?Isthehyperlinkingdoneautomatically?Isthisallmaintainedthroughsomesoftwaretool?Isanyportionofthedocumentationgeneratedautomatically?Ifanyoneknowsaboutthisprocessbetter(oranysimilardocumentationefforts),letmeknow.Wouldliketounderstandandapplyitwhererelevant.Inalotofprojects,documentationisusuallygiventheleastprioritywhichincreasesrelianceonthecoreITteamstounderstandhowasystemactuallyworks.Seeinggoodtechnicaldocumentationthatiseasytonavigateandunderstandhasmademereflectonitsimportance.P.S.:Evenafterallthisinformation,ittookquiteawhilewithafewmisstepstogettheAPIfinallyworkingonmyend.Thatismoreonmyrustyprogramming(it'sbeenawhile).Buthey,theendresultisgreatandthat’sgoodenoughfornow. 21 6Comments Like Comment Share ChanthruKannaChandran Itvariesbasedondifferentprojects. IhaveseenproductmanagersinvolvedearlyduringthedesignphasetocreatetheOpenAPIspec(swagger)whichhasalltheseinformation.AndthesamewillbeconsumedandimplementedbydevelopersasRESTimplementation.Mostofthoseinformationwillbeused/consumedbyprofessionalservicesteamtocreatecustomersexposeddocumentwhichwillhaveabitofhow-toandintro. ThereareafewprojectswherethedevelopersareresponsibletocreateandmaintaintheOpenAPIspectogetherwiththedocumentationthatisneeded. Fromreviewperspective,everyPRgoestoGITwillbereviewedandwellmaintained.IhaveseensomeCIimplementationswhichwillfallifthereisaControllercodechange,buttheOpenAPIspecisnotcurrent. Personally,IfeelhavingthesedocumentationdoneearlyduringthecontractcreationphaseisabetterapproachwhichserveseveryoneinvolvedinSDLCandthecustomers. Like Signintolikethiscomment Reply Signintoreplytothiscomment 4Likes 7mo Reportthiscomment ChanthruKannaChandran Yeah,Jose.Creatingsupportdocumentsandcustomer-specificartifactswillfallunderthem. Like Signintolikethiscomment Reply Signintoreplytothiscomment 1Like 7mo Reportthiscomment JoseSimon Veryinteresting.ThanksforsharingChanthru.'ProfessionalServicesteam'-isthisagroupoftechnicalwriters? ThenoteonCIpipelinesfailingwithoutaspecupdateisnewtome-agoodpractice. Like Signintolikethiscomment Reply Signintoreplytothiscomment 7mo Reportthiscomment VenothA Inmostofthecasesthetechnicaldocumentationwillbepreparedbythedeveloperhimselforthetechnicaldetailswillbeprovidedtocontentwriterorproductowner Like Signintolikethiscomment Reply Signintoreplytothiscomment 1Like 7mo Reportthiscomment VenothA JoseSimonyesdefinitelymultiplepreparationsandreviewwillbedone Like Signintolikethiscomment Reply Signintoreplytothiscomment 7mo Reportthiscomment JoseSimon ThanksVenoth.Ifthedeveloperiswritingthis,theremustbesomepreparation/traininginvolved. Like Signintolikethiscomment Reply Signintoreplytothiscomment 1Like 7mo Reportthiscomment Seemorecomments Tovieworaddacomment,signin Tovieworaddacomment,signin Reading'TheMissingReadme' Mar27,2022 Reading'LightsOut' Jan6,2022 IronViz-Adatastoryin20minutes Nov23,2021