4

As my bachelor's thesis, I'm developing some software (a mocking framework for MATLAB). As such, I often need to reference software documentation - both from MATLAB and the software which serves as my inspiration. It would also be nice to be able to reference the documentation of the specific feature I'm referring to (the analogue of referencing a specific page in a book). However, I mostly access this documentation online and by its nature it tends to exist just in electronic form, which is not really recommended in publishing. So far, the best I've come up with is this:

@misc{mockitoFeatures,
 author = {{\em mockito} developers},
 title = {Features and Motivations},
 note = {\url{https://code.google.com/p/mockito/wiki/FeaturesAndMotivations}},
 urldate = {2013-04-24},
}

(ok strictly speaking, this isn't part of the official docs but it serves the same purpose: it's a specific page and it's only available online)

Specific questions:

  • Who should be the author? In the case of MATLAB I guess it's Mathworks or somesuch; I guess listing open-source projects as "xx developers" is the best I can do.
  • How should I mention the version? Urldate helps in general, but if I'm referring to a particular software version, where should I put this info? In the title?
  • Are there any "official" MATLAB citation recommendations? MATLAB is used in research a lot, perhaps there's a suggested way of doing it and I'm just missing it. The rest of the question still applies for other software, though.
  • Related (duplicate?): academia.stackexchange.com/q/5482/102 – user102 Apr 24 '13 at 19:50
  • Also somewhat related: academia.stackexchange.com/questions/8098/… – Irwin Apr 24 '13 at 21:27
  • 1
    open source projects often tell you how to cite, e.g. matplotlib.org/citing.html – Bitwise Apr 24 '13 at 21:45
  • "Do your best, and don't worry too much about it." These were official directions provided about Internet resources before Academia started to catch up with technology and realize that websites were interesting. If you have something that has no category, simply choose another format that does have some rules, and adapt as best as you can. If no instructions clearly match, most graders won't penalize you for something that has no clear instructions/precedent. If you are going to be judged/graded by someone who can provide you with support ahead of time, check your results before submission – TOOGAM Apr 8 '16 at 20:43
4

In general, I would treat software documentation depending on how it's distributed.

  • If it's published in book form, then it should be cited as a book. The version number goes where you would put the edition, and the company that manufactures the software is the "publisher."

  • If the manual is distributed electronically, then you should cite the website from which it is obtained as the "source."

  • An exception to this is if you are asked in the documentation to reference a specific work (for instance, a research article, or a website) when citing a code. Then you should follow the specific guidance provided.

2

In addition to @aeismail's answer:

  • In my field it is common to refer to Matlab in the text "Matlab version X.Y (The Mathworks, USA)"
  • as @Bitwise comments, scientific FOSS often specifies how cite. So we refer e.g. to R as a normal book. R's recommended citation includes the version.

  • If the version is not included in the recommended citation, I put it into the note field (Bibtex) - that's the R way of putting together such citations:

    > citation ("cbmodels")
    
    To cite package ‘cbmodels’ in publications use:
    
      C. Beleites (2013). cbmodels: Collection of "combined" models:
      PCA-LDA, PLS-LDA, etc.. R package version 0.5-20130417.
    
    A BibTeX entry for LaTeX users is
    
    @Manual{,
        title = {cbmodels: Collection of "combined" models: PCA-LDA, PLS-LDA, etc.},
        author = {C. Beleites},
        year = {2013},
        note = {R package version 0.5-20130417},
      }
    
  • If there's a "normal" publication, I combine the normal citation data with additional URL and version information:

    > citation ("softclassval")
    
    To cite package 'softclassval' please use:
    
      Claudia Beleites, Reiner Salzer and Valter Sergo: 'Validation of Soft
      Classification Models using Partial Class Memberships: An Extended
      Concept of Sensitivity & Co. applied to grading of astrocytoma
      tissues', Chemometrics and Intelligent Laboratory Systems, 122
      (2013), 12 - 22, DOI: 10.1016/j.chemolab.2012.12.003, arXiv:
      1301.0264, R package version 1.0-20130318,
      http://softclassval.r-forge.r-project.org.
    
    A BibTeX entry for LaTeX users is
    
      @Article{,
        title = {Validation of Soft Classification Models using Partial Class Memberships: An Extended Concept of Sensitivity & Co. applied to Grading of Astrocytoma Tissues},
        author = {Claudia Beleites and Reiner Salzer and Valter Sergo},
        year = {2013},
        number = {122},
        pages = {12 -- 22},
        journal = {Chemometrics and Intelligent Laboratory Systems},
        note = {R package version 1.0-20130318},
        url = {http://softclassval.r-forge.r-project.org},
        doi = {10.1016/j.chemolab.2012.12.003},
        eprint = {http://arxiv.org/abs/1301.0264},
      }
    

    (Here, I don't need an additional date, because the release date is included in the version number.

  • I've been using other FOSS software where I did not find a specification, so I asked the developers how they want to be cited.
    The experience is that the developers usually are very happy about this kind of question.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.