Patterns of Knowledge in API Reference Documentation
Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API by providing information not obvious from the API syntax. To improve the quality of reference documentation and the efficiency with which th...
Saved in:
| Published in | IEEE transactions on software engineering Vol. 39; no. 9; pp. 1264 - 1282 |
|---|---|
| Main Authors | , |
| Format | Journal Article |
| Language | English |
| Published |
New York
IEEE
01.09.2013
IEEE Computer Society |
| Subjects | |
| Online Access | Get full text |
Cover
Loading…
| Abstract | Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API by providing information not obvious from the API syntax. To improve the quality of reference documentation and the efficiency with which the relevant information it contains can be accessed, we must first understand its content. We report on a study of the nature and organization of knowledge contained in the reference documentation of the hundreds of APIs provided as a part of two major technology platforms: Java SDK 6 and .NET 4.0. Our study involved the development of a taxonomy of knowledge types based on grounded methods and independent empirical validation. Seventeen trained coders used the taxonomy to rate a total of 5,574 randomly sampled documentation units to assess the knowledge they contain. Our results provide a comprehensive perspective on the patterns of knowledge in API documentation: observations about the types of knowledge it contains and how this knowledge is distributed throughout the documentation. The taxonomy and patterns of knowledge we present in this paper can be used to help practitioners evaluate the content of their API documentation, better organize their documentation, and limit the amount of low-value content. They also provide a vocabulary that can help structure and facilitate discussions about the content of APIs. |
|---|---|
| AbstractList | Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API by providing information not obvious from the API syntax. To improve the quality of reference documentation and the efficiency with which the relevant information it contains can be accessed, we must first understand its content. We report on a study of the nature and organization of knowledge contained in the reference documentation of the hundreds of APIs provided as a part of two major technology platforms: Java SDK 6 and .NET 4.0. Our study involved the development of a taxonomy of knowledge types based on grounded methods and independent empirical validation. Seventeen trained coders used the taxonomy to rate a total of 5,574 randomly sampled documentation units to assess the knowledge they contain. Our results provide a comprehensive perspective on the patterns of knowledge in API documentation: observations about the types of knowledge it contains and how this knowledge is distributed throughout the documentation. The taxonomy and patterns of knowledge we present in this paper can be used to help practitioners evaluate the content of their API documentation, better organize their documentation, and limit the amount of low-value content. They also provide a vocabulary that can help structure and facilitate discussions about the content of APIs. Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API by providing information not obvious from the API syntax. To improve the quality of reference documentation and the efficiency with which the relevant information it contains can be accessed, we must first understand its content. We report on a study of the nature and organization of knowledge contained in the reference documentation of the hundreds of APIs provided as a part of two major technology platforms: Java SDK 6 and .NET 4.0. Our study involved the development of a taxonomy of knowledge types based on grounded methods and independent empirical validation. Seventeen trained coders used the taxonomy to rate a total of 5,574 randomly sampled documentation units to assess the knowledge they contain. Our results provide a comprehensive perspective on the patterns of knowledge in API documentation: observations about the types of knowledge it contains and how this knowledge is distributed throughout the documentation. The taxonomy and patterns of knowledge we present in this paper can be used to help practitioners evaluate the content of their API documentation, better organize their documentation, and limit the amount of low-value content. They also provide a vocabulary that can help structure and facilitate discussions about the content of APIs. [PUBLICATION ABSTRACT] |
| Author | Maalej, W. Robillard, M. P. |
| Author_xml | – sequence: 1 givenname: W. surname: Maalej fullname: Maalej, W. email: maalej@informatik.uni-hamburg.de organization: Dept. of Inf., Univ. of Hamburg, Hamburg, Germany – sequence: 2 givenname: M. P. surname: Robillard fullname: Robillard, M. P. email: martin@cs.mcgill.ca organization: Sch. of Comput. Sci., McGill Univ., Montreal, QC, Canada |
| BookMark | eNp1kMFLwzAUxoNMcJuePHopeBGkMy9p2vQ45tThwKHzHLL4Ih1dMpMW8b-3c-Jh4Oldft_H934D0nPeISHnQEcAtLxZvkxHjAIfATsifSh5mXLBaI_0KS1lKoQsT8ggxjWlVBSF6JNsoZsGg4uJt8mj8581vr1jUrlkvJglz2gxoDOY3HrTbtA1uqm8OyXHVtcRz37vkLzeTZeTh3T-dD-bjOep4ZI2qcxXTHMtQANjDAVao1GsMp0zkzFDOZQSIRd0JcFKKoXIqMVcWGuY1QXlQ3K1790G_9FibNSmigbrWjv0bVSQF5CxMst4h14eoGvfBtetUzukKKT8KYQ9ZYKPMaBVptq_1ARd1Qqo2nlUnUe186iAdZnrg8w2VBsdvv6hL_Z0hYh_ZJ4VnRHg3wKne7s |
| CODEN | IESEDJ |
| CitedBy_id | crossref_primary_10_1016_j_jss_2016_06_101 crossref_primary_10_1109_TSE_2020_3047088 crossref_primary_10_1016_j_cola_2022_101189 crossref_primary_10_1016_j_infsof_2024_107425 crossref_primary_10_1145_3702976 crossref_primary_10_1080_0960085X_2020_1831834 crossref_primary_10_1007_s10664_025_10618_0 crossref_primary_10_1109_TSE_2015_2431680 crossref_primary_10_1002_widm_1369 crossref_primary_10_1109_TSE_2022_3216279 crossref_primary_10_1109_MS_2019_2919840 crossref_primary_10_1145_3489465 crossref_primary_10_1007_s10664_021_10072_8 crossref_primary_10_1007_s11390_021_0235_1 crossref_primary_10_1145_3546949 crossref_primary_10_1109_TSE_2020_3040935 crossref_primary_10_1007_s10515_023_00401_0 crossref_primary_10_1007_s11219_018_9428_4 crossref_primary_10_1007_s11219_019_09476_z crossref_primary_10_1016_j_infsof_2025_107676 crossref_primary_10_1145_3708518 crossref_primary_10_1145_3468744_3468753 crossref_primary_10_1007_s10664_021_09962_8 crossref_primary_10_1007_s11390_020_0042_0 crossref_primary_10_1002_pra2_2018_14505501171 crossref_primary_10_3390_electronics11193053 crossref_primary_10_4018_IJEIS_2019070105 crossref_primary_10_1007_s00287_019_01185_y crossref_primary_10_1007_s10664_019_09694_w crossref_primary_10_1007_s00500_023_09054_3 crossref_primary_10_1016_j_jss_2022_111265 crossref_primary_10_1109_TSE_2019_2919304 crossref_primary_10_7717_peerj_cs_2115 crossref_primary_10_3390_fi11020052 crossref_primary_10_1007_s10664_023_10345_4 crossref_primary_10_1007_s00766_018_0293_2 crossref_primary_10_1016_j_cola_2023_101201 crossref_primary_10_1109_ACCESS_2024_3425830 crossref_primary_10_1007_s10515_024_00442_z crossref_primary_10_1007_s10664_022_10280_w crossref_primary_10_1145_3565799 crossref_primary_10_1016_j_infsof_2014_01_008 crossref_primary_10_1016_j_jss_2019_07_002 crossref_primary_10_1007_s10664_020_09857_0 crossref_primary_10_1145_3434280 crossref_primary_10_1007_s10664_014_9323_y crossref_primary_10_1145_2622669 crossref_primary_10_1145_3447808 crossref_primary_10_3390_electronics13061112 crossref_primary_10_1016_j_eswa_2024_125524 crossref_primary_10_1109_TDSC_2022_3144697 crossref_primary_10_1007_s10664_015_9411_7 crossref_primary_10_1142_S0218194023500547 crossref_primary_10_1002_cpe_7990 crossref_primary_10_1007_s11432_019_1520_6 crossref_primary_10_1016_j_jss_2024_112296 crossref_primary_10_1109_TSE_2021_3120203 crossref_primary_10_1109_TSE_2019_2901459 crossref_primary_10_1109_TKDE_2022_3168611 crossref_primary_10_1109_TSE_2023_3332568 crossref_primary_10_1007_s10664_022_10235_1 crossref_primary_10_1109_TSE_2019_2900245 crossref_primary_10_1007_s10664_018_9660_3 crossref_primary_10_1109_TSE_2020_2981898 crossref_primary_10_1177_0047281617721853 |
| Cites_doi | 10.1145/1029894.1029925 10.1007/s10664-010-9150-8 10.1109/ASE.1998.732658 10.1007/s10664-006-9027-z 10.1109/WPC.1998.693322 10.1007/978-3-642-19811-3_29 10.1109/TSE.2008.26 10.1145/1984701.1984706 10.1145/1453101.1453117 10.1145/1806799.1806828 10.1109/VLHCC.2008.4639083 10.1109/52.476280 10.1145/584955.584976 10.1145/318372.318577 10.1109/ICSE.2007.85 10.1109/ICSE.2007.45 10.1109/APSEC.1998.733596 10.4135/9781071802878 10.18637/jss.v014.i15 10.4135/9781452230153 10.1023/A:1008627026003 10.1145/351936.351951 10.1109/MS.2009.193 10.1007/978-3-642-00427-8_6 10.1145/169059.169061 10.1109/KBSE.1995.490131 10.1109/MSR.2010.5463344 10.2307/2529310 10.1145/1882291.1882312 10.1007/s10664-011-9186-4 10.1109/WPC.2005.47 |
| ContentType | Journal Article |
| Copyright | Copyright IEEE Computer Society Sep 2013 |
| Copyright_xml | – notice: Copyright IEEE Computer Society Sep 2013 |
| DBID | 97E RIA RIE AAYXX CITATION JQ2 K9. 7SC 7SP 8FD F28 FR3 L7M L~C L~D |
| DOI | 10.1109/TSE.2013.12 |
| DatabaseName | IEEE All-Society Periodicals Package (ASPP) 2005–Present IEEE All-Society Periodicals Package (ASPP) 1998–Present IEEE Electronic Library (IEL) CrossRef ProQuest Computer Science Collection ProQuest Health & Medical Complete (Alumni) Computer and Information Systems Abstracts Electronics & Communications Abstracts Technology Research Database ANTE: Abstracts in New Technology & Engineering Engineering Research Database Advanced Technologies Database with Aerospace Computer and Information Systems Abstracts Academic Computer and Information Systems Abstracts Professional |
| DatabaseTitle | CrossRef ProQuest Health & Medical Complete (Alumni) ProQuest Computer Science Collection Technology Research Database Computer and Information Systems Abstracts – Academic Electronics & Communications Abstracts Computer and Information Systems Abstracts Engineering Research Database Advanced Technologies Database with Aerospace ANTE: Abstracts in New Technology & Engineering Computer and Information Systems Abstracts Professional |
| DatabaseTitleList | ProQuest Health & Medical Complete (Alumni) Technology Research Database |
| Database_xml | – sequence: 1 dbid: RIE name: IEEE Electronic Library (IEL) url: https://proxy.k.utb.cz/login?url=https://ieeexplore.ieee.org/ sourceTypes: Publisher |
| DeliveryMethod | fulltext_linktorsrc |
| Discipline | Computer Science |
| EISSN | 1939-3520 |
| EndPage | 1282 |
| ExternalDocumentID | 3062536501 10_1109_TSE_2013_12 6473801 |
| Genre | orig-research Feature |
| GroupedDBID | --Z -DZ -~X .4S .DC 0R~ 29I 3EH 4.4 5GY 5VS 6IK 7WY 7X7 85S 88E 88I 8FE 8FG 8FI 8FJ 8FL 8G5 8R4 8R5 97E 9M8 AAJGR AARMG AASAJ AAWTH ABAZT ABFSI ABJCF ABPPZ ABQJQ ABUWG ABVLG ACGFO ACGOD ACIWK ACNCT ADBBV AENEX AETIX AFKRA AGQYO AGSQL AHBIQ AI. AIBXA AKJIK AKQYR ALLEH ALMA_UNASSIGNED_HOLDINGS ARAPS ARCSS ASUFR ATWAV AZQEC BEFXN BENPR BEZIV BFFAM BGLVJ BGNUA BKEBE BKOMP BPEOZ BPHCQ BVXVI CCPQU CS3 DU5 DWQXO E.L EBS EDO EJD FRNLG FYUFA GNUQQ GROUPED_ABI_INFORM_RESEARCH GUQSH HCIFZ HMCUK HZ~ H~9 I-F IBMZZ ICLAB IEDLZ IFIPE IFJZH IPLJI ITG ITH JAVBF K60 K6V K6~ K7- L6V LAI M0C M1P M1Q M2O M2P M43 M7S MS~ O9- OCL OHT P2P P62 PHGZM PHGZT PJZUB PPXIY PQBIZ PQBZA PQGLB PQQKQ PROAC PSQYO PTHSS PUEGO Q2X RIA RIE RNI RNS RXW RZB S10 TAE TN5 TWZ UHB UKHRP UPT UQL VH1 WH7 XOL YYP YZZ ZCG AAYOK AAYXX ALIPV CITATION RIG JQ2 K9. 7SC 7SP 8FD F28 FR3 L7M L~C L~D |
| ID | FETCH-LOGICAL-c380t-86b2a3a51a1222e5efcae5b4a62c42c03198e1650b81f8085540fe65ffc2fa703 |
| IEDL.DBID | RIE |
| ISSN | 0098-5589 |
| IngestDate | Thu Jul 10 23:04:37 EDT 2025 Mon Jun 30 08:55:12 EDT 2025 Tue Jul 01 05:18:39 EDT 2025 Thu Apr 24 23:06:29 EDT 2025 Wed Aug 27 02:47:44 EDT 2025 |
| IsPeerReviewed | true |
| IsScholarly | true |
| Issue | 9 |
| Language | English |
| License | https://ieeexplore.ieee.org/Xplorehelp/downloads/license-information/IEEE.html |
| LinkModel | DirectLink |
| MergedId | FETCHMERGED-LOGICAL-c380t-86b2a3a51a1222e5efcae5b4a62c42c03198e1650b81f8085540fe65ffc2fa703 |
| Notes | SourceType-Scholarly Journals-1 ObjectType-Feature-1 content type line 14 ObjectType-Article-1 ObjectType-Feature-2 content type line 23 |
| PQID | 1429778870 |
| PQPubID | 21418 |
| PageCount | 19 |
| ParticipantIDs | proquest_journals_1429778870 crossref_primary_10_1109_TSE_2013_12 crossref_citationtrail_10_1109_TSE_2013_12 proquest_miscellaneous_1671429443 ieee_primary_6473801 |
| ProviderPackageCode | CITATION AAYXX |
| PublicationCentury | 2000 |
| PublicationDate | 2013-09-01 |
| PublicationDateYYYYMMDD | 2013-09-01 |
| PublicationDate_xml | – month: 09 year: 2013 text: 2013-09-01 day: 01 |
| PublicationDecade | 2010 |
| PublicationPlace | New York |
| PublicationPlace_xml | – name: New York |
| PublicationTitle | IEEE transactions on software engineering |
| PublicationTitleAbbrev | TSE |
| PublicationYear | 2013 |
| Publisher | IEEE IEEE Computer Society |
| Publisher_xml | – name: IEEE – name: IEEE Computer Society |
| References | ref13 ref35 ref12 ref34 ref15 ref14 ref30 ref33 ref32 ref2 ref1 ref17 ref16 ref19 ref18 Pagano (ref27) 2012 ref24 ref23 Gunderloy (ref11) 2002 ref26 Gravetter (ref10) 2005 ref25 ref20 ref22 ref21 Rosnow (ref31) 2007 ref28 ref29 ref8 ref7 ref9 ref4 ref3 ref6 ref5 |
| References_xml | – ident: ref5 doi: 10.1145/1029894.1029925 – ident: ref30 doi: 10.1007/s10664-010-9150-8 – ident: ref7 doi: 10.1109/ASE.1998.732658 – ident: ref18 doi: 10.1007/s10664-006-9027-z – ident: ref8 doi: 10.1109/WPC.1998.693322 – ident: ref32 doi: 10.1007/978-3-642-19811-3_29 – ident: ref33 doi: 10.1109/TSE.2008.26 – ident: ref28 doi: 10.1145/1984701.1984706 – start-page: 1 year: 2012 ident: ref27 article-title: How Do Open Source Communities Blog? publication-title: Empirical Software Eng. – ident: ref35 doi: 10.1145/1453101.1453117 – ident: ref9 doi: 10.1145/1806799.1806828 – ident: ref34 doi: 10.1109/VLHCC.2008.4639083 – volume-title: Understanding and Using Assemblies and Namespaces in .NET, Microsoft Corp. year: 2002 ident: ref11 – ident: ref17 doi: 10.1109/52.476280 – ident: ref26 doi: 10.1145/584955.584976 – ident: ref20 doi: 10.1145/318372.318577 – ident: ref6 doi: 10.1109/ICSE.2007.85 – ident: ref19 doi: 10.1109/ICSE.2007.45 – ident: ref1 doi: 10.1109/APSEC.1998.733596 – ident: ref25 doi: 10.4135/9781071802878 – ident: ref12 doi: 10.18637/jss.v014.i15 – ident: ref3 doi: 10.4135/9781452230153 – volume-title: Essentials of Statistics for the Behavioral Sciences year: 2005 ident: ref10 – ident: ref24 doi: 10.1023/A:1008627026003 – ident: ref2 doi: 10.1145/351936.351951 – ident: ref29 doi: 10.1109/MS.2009.193 – ident: ref15 doi: 10.1007/978-3-642-00427-8_6 – ident: ref13 doi: 10.1145/169059.169061 – ident: ref16 doi: 10.1109/KBSE.1995.490131 – ident: ref22 doi: 10.1109/MSR.2010.5463344 – ident: ref21 doi: 10.2307/2529310 – volume-title: Beginning Behavioral Research: A Conceptual Primer year: 2007 ident: ref31 – ident: ref4 doi: 10.1145/1882291.1882312 – ident: ref23 doi: 10.1007/s10664-011-9186-4 – ident: ref14 doi: 10.1109/WPC.2005.47 |
| SSID | ssj0005775 ssib053395008 |
| Score | 2.4574304 |
| Snippet | Reading reference documentation is an important part of programming with application programming interfaces (APIs). Reference documentation complements the API... |
| SourceID | proquest crossref ieee |
| SourceType | Aggregation Database Enrichment Source Index Database Publisher |
| StartPage | 1264 |
| SubjectTerms | API API documentation Application programming interface Complement content analysis data mining Documentation empirical study Encoding grounded method Java Java (programming language) Knowledge NET pattern mining Platforms Programming Programming languages Reliability Sociology Software software documentation Studies Syntax Taxonomy Vocabularies & taxonomies |
| Title | Patterns of Knowledge in API Reference Documentation |
| URI | https://ieeexplore.ieee.org/document/6473801 https://www.proquest.com/docview/1429778870 https://www.proquest.com/docview/1671429443 |
| Volume | 39 |
| hasFullText | 1 |
| inHoldings | 1 |
| isFullTextHit | |
| isPrint | |
| link | http://utb.summon.serialssolutions.com/2.0.0/link/0/eLvHCXMwjV3fS8MwED7mnnxx6hTnLyLsSezWtEnaPYo6pqIIbrC3kqQXEKUTt73415tkbUXdg2-FHknI5ZK75LvvALomSSUmiQxQcRMwkQtrUg4mprUROSYyVB5t8ShGE3Y35dMGXNS5MIjowWfYc5_-LT-f6aW7KusLlsSpS9basIHbKlfrG86RJLzix-Q8HZS5eDQc9MfPNw7DFfdo9OP08eVU_uzB_mAZtuChGtIKT_LaWy5UT3_-Ymv875i3Yav0MMnlaknsQAOLXWhV1RtIacxtYE-eWrOYk5kh99XVGnkpyOXTLakJaMl12YdX4R5Mhjfjq1FQ1lAItO12EaRCRTKWnEpqPQHkaLRErpgUkWaRdjlMKVLrpqmUmtSD1kKDghujIyPtdrAPzWJW4AEQlQ8EzRVjxh7pNqhOpRSSGcrQEQQZ2oHzam4zXRKMuzoXb5kPNMJBZhWROUVkNOpAtxZ-X_FqrBdruymtRcrZ7MBxpbSstLm5DWIi68zaTTPswFn921qLewKRBc6WVkYkToyx-HB9y0ewGfmCFw5FdgzNxccST6zbsVCnfr19AS300-U |
| linkProvider | IEEE |
| linkToHtml | http://utb.summon.serialssolutions.com/2.0.0/link/0/eLvHCXMwzV3BbtQwEB2VcoALBQrqlgJGKhekbGOv7SQHDhVttcuWqhJbqbdgO2MJgbKI3VUF38Kv8G-MvU4Q0GslbpEyshLPeGZsv3kDsO-L0mBRmAyt8pnUjaYlFWBiznndYGFyG9EWZ3p8Id9eqssN-NHXwiBiBJ_hMDzGu_xm7lbhqOxAy2JEHjVBKKf47Yo2aIvXkyPS5kshTo5nb8ZZ6iGQORJdZqW2woyM4oZTJESF3hlUVhotnBQu1PCUyClNsSX3ZQRt5R618t4Jb2g50Li34DblGUqsq8N-A0iKQnWMnEqVVar-43l1MHt_HFBjoyEXf8S72MDlH68fQ9nJFvzsJmGNYPk0XC3t0H3_ix_yf52l-3Av5dDscG30D2AD24ew1fWnYMldbYM8j-Sh7YLNPZt2h4fsY8sOzyesp9hlR-mfopE-gosb-fbHsNnOW9wBZptK88ZK6Slp0VVeGqON9FxioEDyfACvOl3WLlGoh04en-u4lcqrmhRfB8XXXAxgvxf-smYOuV5sO6iwF0naG8BeZyR18ioL2qYJStcpLOQDeNG_Jn8QLnlMi_MVyegiiEk52r1-5OdwZzx7d1qfTs6mT-CuiO09AmZuDzaXX1f4lJKspX0WbZ3Bh5s2m18u4jDU |
| openUrl | ctx_ver=Z39.88-2004&ctx_enc=info%3Aofi%2Fenc%3AUTF-8&rfr_id=info%3Asid%2Fsummon.serialssolutions.com&rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Ajournal&rft.genre=article&rft.atitle=Patterns+of+Knowledge+in+API+Reference+Documentation&rft.jtitle=IEEE+transactions+on+software+engineering&rft.au=Maalej%2C+Walid&rft.au=Robillard%2C+Martin+P&rft.date=2013-09-01&rft.pub=IEEE+Computer+Society&rft.issn=0098-5589&rft.eissn=1939-3520&rft.volume=39&rft.issue=9&rft.spage=1264&rft_id=info:doi/10.1109%2Ftse.2013.12&rft.externalDBID=NO_FULL_TEXT&rft.externalDocID=3062536501 |
| thumbnail_l | http://covers-cdn.summon.serialssolutions.com/index.aspx?isbn=/lc.gif&issn=0098-5589&client=summon |
| thumbnail_m | http://covers-cdn.summon.serialssolutions.com/index.aspx?isbn=/mc.gif&issn=0098-5589&client=summon |
| thumbnail_s | http://covers-cdn.summon.serialssolutions.com/index.aspx?isbn=/sc.gif&issn=0098-5589&client=summon |