At times, you have to build docs that cover not only REST-y APIs but also frontend SDKs. What do you do, when you have to offer docs for multiple such SDKs, based on different frameworks, under rapid, uncoordinated development with multiple feature enhancements per iteration and at times, with breaking changes, but versioned and searchable?

1. unRESTamongthedocs

2. Whatarewegoingtotalkabout
Designingthedocs
Forabetterdeveloperexperience
unRESTamongthedocs
2

3. Whoisthisdiscussionfor
Technicalwriters-becausetheyarefacedwithsuchproblemsanddilemmasalmost
daily
Designers-whoareworkingontechnicalinformationsystems
Developers-whowanttobebetteratwritingsystems
unRESTamongthedocs
3

4. whoami
AkshayBhalotia
Professionalinterests
Paymentsystems
DeveloperSaaS
Personalinterests
Cats-prouddadto2cats
Boardgames
Mechanicalkeyboards
Findmehere
unRESTamongthedocs
4

5. Butwhywouldyoulistentome
I'veseensome inmylife
AniOSDeveloperatanoutsourcingboutique(OptimusInformation,Inc.)anda
FinTechAPIstartup(Razorpay)
Anaccountmanagerattecheventsandmediacompany(HasGeek)
SupportandsolutionsengineeratanotherFinTechAPIstartup(Setu)
Developerrelationsmanageratareal-timevideoAPIstartup(Dyte)
Andnow,aproductmanageratadatagatewayAPIcompany(Phyllo)
unRESTamongthedocs
5

6. Problem
unRESTamongthedocs
6

7. Docsarehard
Primaryfunction:giveinfo
But
inaneasilyreadablemanner
inaneasilyfindablemanner
helpwiththenextsteps
giveenoughbutnottoomuch
expectreturningusers
unRESTamongthedocs
7

8. Whatisharder
DocumentingfrontendSDKs
DocumentingUIfeatures
Withversioncontrol
Feature-basedreleases,withoutareleasecycle
Breakingchanges
unRESTamongthedocs
8

9. Let'sseeafewexamplesofhowI'vetriedtackling
someofthesechallenges
unRESTamongthedocs
9

10. Razorpay-PaymentAPIsforIndia
Anintropagehelpsthereadernavigatetotheirappropriatesection.
unRESTamongthedocs
10

11. Razorpay-PaymentAPIsforIndia
Whenyouclickonanyoftheoptions,youlandontherelatedoverviewsection,butallthe
otheroptionsareavailableinthesidebarforeasynavigation.
unRESTamongthedocs
11

12. Razorpay-PaymentAPIsforIndia
Allthestepsarelistedwithinthecontext,eveniftheyarenotrelatedtothefrontend.
Contextmatters.Completeinformationhelpsdevelopersmakebetterdecisions.
unRESTamongthedocs
12

13. Razorpay-PaymentAPIsforIndia
Cleardifferentiationandcodesamplesforavailableoptions.
unRESTamongthedocs
13

14. Razorpay-PaymentAPIsforIndia
Properreferenceforallparameters.
unRESTamongthedocs
14

15. Razorpay-PaymentAPIsforIndia
Switchingtosomeotherplatform,sayiOS,followsaverysimilarstructuresothereader
canexpectwhattofindhere.
unRESTamongthedocs
15

16. Razorpay-PaymentAPIsforIndia
Platform-specificinstructionsandvideos/gifsforstepstobeperformedintheIDE.
unRESTamongthedocs
16

17. Razorpay-PaymentAPIsforIndia
Usingcalloutstodrawattentiontospecificpoints.
unRESTamongthedocs
17

18. Dyte-real-timeaudioandvideocallAPIs
Thelandingpageshowsalltheavailableoptions.
unRESTamongthedocs
18

19. Dyte-real-timeaudioandvideocallAPIs
Oneofthebestthingswethinkwedesignedisthenavigation.SeehowboththeUISDK
andCoreSDKarehousedundertheWebSDKsectionbutatthetoplevel.Andwithineach
ofthem,youcanselectadifferentplatformorframework.Thebestpart?Whenyouselect
acomponentorpageandswitchtheframework,thecontextispreserved!
unRESTamongthedocs
19

20. Dyte-real-timeaudioandvideocallAPIs
Strongbeliefin"shownottell"-liveeditor!
unRESTamongthedocs
20

21. Dyte-real-timeaudioandvideocallAPIs
Strongbeliefin"shownottell"-avisualrepresentation
unRESTamongthedocs
21

22. Dyte-real-timeaudioandvideocallAPIs
Strongbeliefin"shownottell"-actualrenders
unRESTamongthedocs
22

23. Dyte-real-timeaudioandvideocallAPIs
Strongbeliefin"shownottell"-gifswhichshowtheeffectofcodechange
unRESTamongthedocs
23

24. Dyte-real-timeaudioandvideocallAPIs
Allrelevantinfoatasingleplace.
unRESTamongthedocs
24

25. Dyte-real-timeaudioandvideocallAPIs
Allrelevantinfoatasingleplace.
unRESTamongthedocs
25

26. Dyte-real-timeaudioandvideocallAPIs
Butalsoseparatelyasareference.
unRESTamongthedocs
26

27. Dyte-real-timeaudioandvideocallAPIs
Bonus-Designfordevelopers!
unRESTamongthedocs
27

28. Phyllo-Datagatewayforthedigitaleconomy
CleardemarcationforSDKandAPIsections
unRESTamongthedocs
28

29. Phyllo-Datagatewayforthedigitaleconomy
Glossarytowardsthebeginning
unRESTamongthedocs
29

30. Phyllo-Datagatewayforthedigitaleconomy
Visualindicatorsfortheflow
unRESTamongthedocs
30

31. Phyllo-Datagatewayforthedigitaleconomy
Visualreferenceforthecomponents
unRESTamongthedocs
31

32. Phyllo-Datagatewayforthedigitaleconomy
Acleardistinctionbetweenweb(whichisbrowser-based)andmobilenativeSDKs
unRESTamongthedocs
32

33. Phyllo-Datagatewayforthedigitaleconomy
Thereisachoicebetweentwooptions
unRESTamongthedocs
33

34. Phyllo-Datagatewayforthedigitaleconomy
Whichisclearlyexplainedanddifferenceshighlighted
unRESTamongthedocs
34

35. Phyllo-Datagatewayforthedigitaleconomy
Alongwithacalloutforthemostcommonmistake/misunderstoodpath
unRESTamongthedocs
35

36. Phyllo-Datagatewayforthedigitaleconomy
Andthatmisunderstoodpath-mobilein-appbrowsing-alsogetsapageofitsownto
explainthingsbetter
unRESTamongthedocs
36

37. Phyllo-Datagatewayforthedigitaleconomy
Trytokeeptheflowandexplanationofstepssame,orasmuchsimilaraspossible
unRESTamongthedocs
37

38. Phyllo-Datagatewayforthedigitaleconomy
Maintainachangelog(thisisprobablynotthebestwaybutworkwithwhateveryouhave)
unRESTamongthedocs
38

39. Let'sseeafewexamplesofhowI'veseenothersgive
itago
unRESTamongthedocs
39

40. Itriedturningtowardstwoofthemostpopularfrontendframeworksthatareusedtobuild
modernapps,andhereiswhatIfound.
unRESTamongthedocs
40

41. ReactJS
Youwouldimaginesomethingthatissopopularlyusedtobuildinterfacesandvisual
componentswouldhavemorevisualdiversityinthedocs.
unRESTamongthedocs
41

42. VueJS
Buttheyareratherboringwallsofmethodreferencesandguides/tutorials.
unRESTamongthedocs
42

43. Lottie
Somethingthatisusedtobuildanimationshasabsolutelynoanimationsonthedocsand
justalotoftext.
unRESTamongthedocs
43

44. Auth0
Providealotofstarterkitsandguidesfordifferentframeworks.
unRESTamongthedocs
44

45. Agora
Makeitabreezetointeroperate.
unRESTamongthedocs
45

46. Andlastly,wehavetheloveofalldocumentationgeeks,thatprobablyeveryonelooksup
to.
unRESTamongthedocs
46

47. Stripe
Stripeprovidestwofrontendintegrations-StripeCheckout(pre-builtcompletecheckout
UI)andStripeElements(componentstobuildthepaymentspartofyourcheckout
experience).Hereishowtheydocumentboth.
unRESTamongthedocs
47

48. Stripe
Introducethefeatureonalandingpageandgivethemostcommonoptionstoreadfurther
about.
unRESTamongthedocs
48

49. Stripe
Butwhyitworkssowellisthattheyalsoprovidesortofalivecodeintegration
walkthrough.Thisiswhereyoulandwhenyouclick"getstartedwithElements".
unRESTamongthedocs
49

50. Stripe
Verysimilarexperienceforthepre-builtcheckoutsectiontoo,sincemostoptionsonthat
screen(suchaspaymentmethods,collectaddress,etc.)arecontrolledbytheAPIrequest
youmakebeforestartingthepayment.
unRESTamongthedocs
50

51. Stripe
Despitethisgreatstep-by-stephandholding,theyhavecompletereferencesfortheir
SDKsincasesomeonewouldliketomakeuseofaspecificcomponentforaspecificuse
case,oratinkererwouldliketotinker.
unRESTamongthedocs
51

52. Conclusion
Idon'tknowiftherearerulesorguidelinesthatIcangiveyou.It'sallverycontextualand
that'snotgreat.
Whatwecancertainlydo
Thinkoftheuser
Thinkaboutwhatmatterstothem
Trynottooverwhelm
Butkeepinformationaccessible
Interoperabilityanddrawingparallelsbetweenframeworkshelp
unRESTamongthedocs
52

53. Mysincerewish
Standardsformethoddefinitions,acrosslanguagesandframeworks,includingUI
components
unRESTamongthedocs
53

54. Thankyouforlisteningtomyrant
Accesstheslidesathttps://github.com/akshaybhalotia/unREST-among-the-docs.
Icantryansweringyourquestionsnow,noguaranteesthough.
unRESTamongthedocs
54