Good documentation - the YouTube Data API - LinkedIn

Recently, I wanted to get some information about a few YouTube channels and ended up exploring the YouTube Data API. I expected the learning ... 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. 22 6Comments Like Comment Share ChanthruKannaChandran Itvariesbasedondifferentprojects. IhaveseenproductmanagersinvolvedearlyduringthedesignphasetocreatetheOpenAPIspec(swagger)whichhasalltheseinformation.AndthesamewillbeconsumedandimplementedbydevelopersasRESTimplementation.Mostofthoseinformationwillbeused/consumedbyprofessionalservicesteamtocreatecustomersexposeddocumentwhichwillhaveabitofhow-toandintro. ThereareafewprojectswherethedevelopersareresponsibletocreateandmaintaintheOpenAPIspectogetherwiththedocumentationthatisneeded. Fromreviewperspective,everyPRgoestoGITwillbereviewedandwellmaintained.IhaveseensomeCIimplementationswhichwillfallifthereisaControllercodechange,buttheOpenAPIspecisnotcurrent. Personally,IfeelhavingthesedocumentationdoneearlyduringthecontractcreationphaseisabetterapproachwhichserveseveryoneinvolvedinSDLCandthecustomers. Like Signintolikethiscomment Reply Signintoreplytothiscomment 5Likes 10mo Reportthiscomment ChanthruKannaChandran Yeah,Jose.Creatingsupportdocumentsandcustomer-specificartifactswillfallunderthem. Like Signintolikethiscomment Reply Signintoreplytothiscomment 1Like 9mo Reportthiscomment JoseSimon Veryinteresting.ThanksforsharingChanthru.'ProfessionalServicesteam'-isthisagroupoftechnicalwriters? ThenoteonCIpipelinesfailingwithoutaspecupdateisnewtome-agoodpractice. Like Signintolikethiscomment Reply Signintoreplytothiscomment 9mo Reportthiscomment VenothA Inmostofthecasesthetechnicaldocumentationwillbepreparedbythedeveloperhimselforthetechnicaldetailswillbeprovidedtocontentwriterorproductowner Like Signintolikethiscomment Reply Signintoreplytothiscomment 1Like 10mo Reportthiscomment VenothA JoseSimonyesdefinitelymultiplepreparationsandreviewwillbedone Like Signintolikethiscomment Reply Signintoreplytothiscomment 10mo Reportthiscomment JoseSimon ThanksVenoth.Ifthedeveloperiswritingthis,theremustbesomepreparation/traininginvolved. Like Signintolikethiscomment Reply Signintoreplytothiscomment 1Like 10mo Reportthiscomment Seemorecomments Tovieworaddacomment,signin Tovieworaddacomment,signin Reading'TheMissingReadme' Mar27,2022 Reading'LightsOut' Jan6,2022 IronViz-Adatastoryin20minutes Nov23,2021 Stressintheworkplace Oct20,2021 Coordinationofcareinhealthcare Jun30,2021 Thechanginghumanconditionatbusinesses? Jun5,2021 Reading'NoRulesRules:NetflixandtheCultureofReinvention' Jan11,2021 Machines,metrics,andthehuman Sep4,2019 Othersalsoviewed Dataeconomybuiltonhealthcaredata AndyMartin 2mo Investinginweb3 AndyMartin 3mo Exploretopics Workplace JobSearch Careers Interviewing SalaryandCompensation Internships EmployeeBenefits SeeAll