How API Documentation Fails
Formal documentation can be a crucial resource for learning to how to use an API. However, producing high-quality documentation can be nontrivial. Researchers investigated how 10 common documentation problems manifested themselves in practice. The results are based on two surveys of a total of 323 p...
Saved in:
| Published in | IEEE software Vol. 32; no. 4; pp. 68 - 75 |
|---|---|
| Main Authors | , |
| Format | Journal Article |
| Language | English |
| Published |
Los Alamitos
IEEE
01.07.2015
IEEE Computer Society |
| Subjects | |
| Online Access | Get full text |
Cover
Loading…
| Abstract | Formal documentation can be a crucial resource for learning to how to use an API. However, producing high-quality documentation can be nontrivial. Researchers investigated how 10 common documentation problems manifested themselves in practice. The results are based on two surveys of a total of 323 professional software developers and analysis of 179 API documentation units. The three severest problems were ambiguity, incompleteness, and incorrectness of content. The respondents often mentioned six of the 10 problems as "blockers"' that forced them to use another API. |
|---|---|
| AbstractList | Formal documentation can be a crucial resource for learning to how to use an API. However, producing high-quality documentation can be nontrivial. Researchers investigated how 10 common documentation problems manifested themselves in practice. The results are based on two surveys of a total of 323 professional software developers and analysis of 179 API documentation units. The three severest problems were ambiguity, incompleteness, and incorrectness of content. The respondents often mentioned six of the 10 problems as "blockers"' that forced them to use another API. |
| Author | Robillard, Martin P. Uddin, Gias |
| Author_xml | – sequence: 1 givenname: Gias surname: Uddin fullname: Uddin, Gias email: giasu@cs.mcgill.ca organization: Sch. of Comput. Sci., McGill Univ., Montreal, QC, Canada – sequence: 2 givenname: Martin P. surname: Robillard fullname: Robillard, Martin P. email: martin@cs.mcgill.ca organization: Sch. of Comput. Sci., McGill Univ., Montreal, QC, Canada |
| BookMark | eNptj8FLwzAUxoNMcJtevO4y8CZ0vjRpXnMc07nBhsJ2D2maQMfWzKRF_O_tqHgQT-_y-77v_UZkUPvaEnJPYUYpyKftbpYC5bMcrsiQSoYJp5IPyBCQQ4I8kzdkFOMBADLKYEgmK_85nb-vp8_etCdbN7qpfD1d6uoYb8m108do737umOyXL_vFKtm8va4X801iUpRNgkgxLTU441LBkedQGG5ZLvJSQMlKyRkWrpROpgjC6SLNjaBl94uR2iEbk4e-9hz8R2tjow6-DXW3qKiQGVBkyDrqsadM8DEG69Q5VCcdvhQFdXFX2526uKscOhj-wKbqzZrQmf0fmfSRylr7242Ug0DBvgGCW2Ng |
| CODEN | IESOEG |
| CitedBy_id | crossref_primary_10_1007_s11432_019_2745_5 crossref_primary_10_1145_3358931_3358937 crossref_primary_10_1145_3702976 crossref_primary_10_1109_TSE_2019_2903039 crossref_primary_10_3390_info8040148 crossref_primary_10_1109_TSE_2021_3059907 crossref_primary_10_1142_S0218194017500267 crossref_primary_10_1007_s10664_022_10242_2 crossref_primary_10_1007_s10664_022_10244_0 crossref_primary_10_1016_j_csi_2022_103657 crossref_primary_10_1145_3546949 crossref_primary_10_1109_ACCESS_2023_3238813 crossref_primary_10_1109_TSE_2021_3094171 crossref_primary_10_1177_1461444816675438 crossref_primary_10_1016_j_jss_2019_07_101 crossref_primary_10_1007_s10664_020_09857_0 crossref_primary_10_1016_j_scico_2023_102933 crossref_primary_10_1007_s10664_023_10397_6 crossref_primary_10_1145_3691627 crossref_primary_10_1145_3470133 crossref_primary_10_1016_j_procs_2017_11_057 crossref_primary_10_1109_TSE_2020_3023664 crossref_primary_10_1007_s11390_020_0042_0 crossref_primary_10_1109_TSE_2019_2906315 crossref_primary_10_1142_S0218194020500205 crossref_primary_10_1016_j_cosrev_2025_100732 crossref_primary_10_1109_TSE_2019_2901459 crossref_primary_10_1016_j_jss_2022_111265 crossref_primary_10_1145_3439769 crossref_primary_10_1007_s10664_021_10021_5 crossref_primary_10_1109_LRA_2018_2878604 crossref_primary_10_1109_TSE_2019_2919304 crossref_primary_10_1109_TSE_2021_3117023 crossref_primary_10_1007_s10664_022_10156_z crossref_primary_10_1007_s11771_019_4185_5 crossref_primary_10_1145_3444945 crossref_primary_10_1109_TSE_2018_2872971 crossref_primary_10_1016_j_cl_2018_07_006 crossref_primary_10_1177_0047281617721853 |
| Cites_doi | 10.1109/ICSM.2012.6405249 10.1145/2393596.2393648 10.1109/MS.2003.1241364 10.1145/1882291.1882312 10.1007/s10664-010-9150-8 |
| ContentType | Journal Article |
| Copyright | Copyright IEEE Computer Society Jul-Aug 2015 |
| Copyright_xml | – notice: Copyright IEEE Computer Society Jul-Aug 2015 |
| DBID | 97E RIA RIE AAYXX CITATION JQ2 |
| DOI | 10.1109/MS.2014.80 |
| 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 |
| DatabaseTitle | CrossRef ProQuest Computer Science Collection |
| DatabaseTitleList | ProQuest Computer Science Collection |
| 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 | 1937-4194 |
| EndPage | 75 |
| ExternalDocumentID | 3738558291 10_1109_MS_2014_80 7140676 |
| Genre | orig-research Feature |
| GroupedDBID | -DZ -~X .4S .DC 0R~ 29I 3EH 4.4 5GY 5VS 6IK 7WY 85S 88I 8FE 8FG 8FL 8G5 8R4 8R5 97E 9M8 AAJGR AARMG AASAJ AAVXG AAWTH ABAZT ABJCF ABQJQ ABUWG ABVLG ACGFO ACGOD ACIWK AENEX AETIX AFKRA AFOGA AGCDD AGQYO AGSQL AHBIQ AI. AIBXA AKJIK AKQYR ALLEH ALMA_UNASSIGNED_HOLDINGS ARAPS ARCSS ASUFR ATWAV AZLTO AZQEC BEFXN BENPR BEZIV BFFAM BGLVJ BGNUA BKEBE BKOMP BPEOZ BPHCQ CCPQU CS3 DU5 DWQXO EBS EDO EJD FRNLG GNUQQ GUQSH HCIFZ HZ~ H~9 I-F IBMZZ ICLAB IEDLZ IFIPE IFJZH IPLJI ITG ITH JAVBF K60 K6V K6~ K7- L6V LAI M0C M1Q M2O M2P M43 M7S MS~ O9- OCL OHT P2P P62 PHGZM PHGZT PQBIZ PQBZA PQGLB PQQKQ PROAC PTHSS PUEGO Q2X RIA RIE RNI RNS RXW RZB TAE TN5 UHB UKR UQL VH1 WH7 YZZ ZCG AAYOK AAYXX ABGFU CITATION RIG JQ2 |
| ID | FETCH-LOGICAL-c279t-77172da0fcf2647480bc4e3868d60d3d9437bfd9f92706fab28c61d459c9af73 |
| IEDL.DBID | RIE |
| ISSN | 0740-7459 |
| IngestDate | Wed Aug 13 03:20:22 EDT 2025 Tue Jul 01 01:48:34 EDT 2025 Thu Apr 24 23:12:22 EDT 2025 Wed Aug 27 02:44:21 EDT 2025 |
| IsDoiOpenAccess | false |
| IsOpenAccess | true |
| IsPeerReviewed | true |
| IsScholarly | true |
| Issue | 4 |
| Language | English |
| License | https://ieeexplore.ieee.org/Xplorehelp/downloads/license-information/IEEE.html |
| LinkModel | DirectLink |
| MergedId | FETCHMERGED-LOGICAL-c279t-77172da0fcf2647480bc4e3868d60d3d9437bfd9f92706fab28c61d459c9af73 |
| Notes | SourceType-Scholarly Journals-1 ObjectType-Feature-1 content type line 14 |
| PQID | 1695017373 |
| PQPubID | 37787 |
| PageCount | 8 |
| ParticipantIDs | crossref_primary_10_1109_MS_2014_80 ieee_primary_7140676 crossref_citationtrail_10_1109_MS_2014_80 proquest_journals_1695017373 |
| ProviderPackageCode | CITATION AAYXX |
| PublicationCentury | 2000 |
| PublicationDate | 2015-July-Aug. 2015-7-00 20150701 |
| PublicationDateYYYYMMDD | 2015-07-01 |
| PublicationDate_xml | – month: 07 year: 2015 text: 2015-July-Aug. |
| PublicationDecade | 2010 |
| PublicationPlace | Los Alamitos |
| PublicationPlace_xml | – name: Los Alamitos |
| PublicationTitle | IEEE software |
| PublicationTitleAbbrev | S-M |
| PublicationYear | 2015 |
| Publisher | IEEE IEEE Computer Society |
| Publisher_xml | – name: IEEE – name: IEEE Computer Society |
| References | (ref5) 2013 ref2 ref1 ref4 ref3 ref6 |
| References_xml | – ident: ref3 doi: 10.1109/ICSM.2012.6405249 – ident: ref6 doi: 10.1145/2393596.2393648 – ident: ref4 doi: 10.1109/MS.2003.1241364 – ident: ref2 doi: 10.1145/1882291.1882312 – year: 2013 ident: ref5 article-title: APR's Version Numbering – ident: ref1 doi: 10.1007/s10664-010-9150-8 |
| SSID | ssj0005130 |
| Score | 2.502507 |
| Snippet | Formal documentation can be a crucial resource for learning to how to use an API. However, producing high-quality documentation can be nontrivial. Researchers... |
| SourceID | proquest crossref ieee |
| SourceType | Aggregation Database Enrichment Source Index Database Publisher |
| StartPage | 68 |
| SubjectTerms | API Application programming interface Application programming interfaces Documentation Failure analysis Software development software engineering Studies Uniform resource locators user study |
| Title | How API Documentation Fails |
| URI | https://ieeexplore.ieee.org/document/7140676 https://www.proquest.com/docview/1695017373 |
| Volume | 32 |
| hasFullText | 1 |
| inHoldings | 1 |
| isFullTextHit | |
| isPrint | |
| link | http://utb.summon.serialssolutions.com/2.0.0/link/0/eLvHCXMwjV3PS8MwFH7Mnbw4dYpzUwp6EWyXNmnSHIc6plARNmG3kl8FcWziNgT_etO0naI7eOvhJYSXvLwv6ZfvAVwqTmwcxMpnNNY-kTLxRRTmfoRjxak2XLmri_SRjp7JwzSeNuB68xbGGOPIZyYoPt2_fL1Q6-KqrF-Iy1FGd2DHHtzKt1rfdI7Q1RWxGRH5jMS8kiINEe-n44LCRYJC-vFH8nHVVP5swS6vDFuQ1iMq6SSvwXolA_X5S6zxv0Peh70KYHqDckUcQMPMD6FVF2_wqlhuQ3e0-PAGT_febdWJmyJvKF5myyOYDO8mNyO_qpTgq4jxlYXIFodogXKVW4DDSIKkIgYnNNEUaaw5wUzmmuc8YojmQkaJoqG2blJc5AwfQ3O-mJsT8BKMuUGJCiXXJI-5pIrbpgoJEWqhRAeuag9mqlIRL4pZzDJ3mkA8S8dZ4e0sQR242Ni-ldoZW63ahds2FpXHOtCrJyarwmqZhZTHdgvBDJ9ub9WFXdttXPJpe9Bcva_NmUUNK3nulssXECK9jg |
| linkProvider | IEEE |
| linkToHtml | http://utb.summon.serialssolutions.com/2.0.0/link/0/eLvHCXMwzV1LTxsxEB7RcGgvBAqo4VFWanvoYYN3_VofOCAgSoCgSqQSN8uvlVCjBJFECP4Kf4Ufh9frpKjlisRtD-Pdkb_ZmbH9eQbguxHE_wfUpJxRmxKti1TlWZnmmBrBrBMmbF30L1j3Nzm9oldL8Li4C-OcC-Qz164ew1m-HZtZtVW2XxWXY5xFCuWZu7_zC7TJQe_Yo_kjzzsng6NuGnsIpCbnYuqTRx-hrUKlKX3o56RA2hCHC1ZYhiy2gmCuSytKkXPESqXzwrDMEuqVVCXH_rUfYNmnGTSvL4f95Y9koZGJD8Eo5V4-1j7NkNjvX1acMdKuak2-iHahfct_Pj8Esk4TnuZTUPNX_rRnU902D_9Uh3ync7QKKzGBTg5ri1-DJTf6DM15c4ok-qp12O6O75LDX73kOOocTDDpqOvhZAMGb6HhJjRG45H7AkmBsXCoMJkWlpRUaGaEH2qQUplVRrXg5xwwaWKV9KpZx1CG1RISsn8pK3BlgVrwbSF7U9cGeVVqvUJpIREBasHO3A5kdBsTmTFBvYvEHG-9PmoPPnYH_XN53rs424ZP_hO05g7vQGN6O3O7PkOa6q_BUhOQb4z6M6XuGgI |
| 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=How+API+Documentation+Fails&rft.jtitle=IEEE+software&rft.au=Uddin%2C+Gias&rft.au=Robillard%2C+Martin+P.&rft.date=2015-07-01&rft.pub=IEEE&rft.issn=0740-7459&rft.volume=32&rft.issue=4&rft.spage=68&rft.epage=75&rft_id=info:doi/10.1109%2FMS.2014.80&rft.externalDocID=7140676 |
| thumbnail_l | http://covers-cdn.summon.serialssolutions.com/index.aspx?isbn=/lc.gif&issn=0740-7459&client=summon |
| thumbnail_m | http://covers-cdn.summon.serialssolutions.com/index.aspx?isbn=/mc.gif&issn=0740-7459&client=summon |
| thumbnail_s | http://covers-cdn.summon.serialssolutions.com/index.aspx?isbn=/sc.gif&issn=0740-7459&client=summon |