Logo for M Libraries Publishing

Want to create or adapt books like this? Learn more about how Pressbooks supports open publishing practices.

13.1 Formatting a Research Paper

Learning objectives.

  • Identify the major components of a research paper written using American Psychological Association (APA) style.
  • Apply general APA style and formatting conventions in a research paper.

In this chapter, you will learn how to use APA style , the documentation and formatting style followed by the American Psychological Association, as well as MLA style , from the Modern Language Association. There are a few major formatting styles used in academic texts, including AMA, Chicago, and Turabian:

  • AMA (American Medical Association) for medicine, health, and biological sciences
  • APA (American Psychological Association) for education, psychology, and the social sciences
  • Chicago—a common style used in everyday publications like magazines, newspapers, and books
  • MLA (Modern Language Association) for English, literature, arts, and humanities
  • Turabian—another common style designed for its universal application across all subjects and disciplines

While all the formatting and citation styles have their own use and applications, in this chapter we focus our attention on the two styles you are most likely to use in your academic studies: APA and MLA.

If you find that the rules of proper source documentation are difficult to keep straight, you are not alone. Writing a good research paper is, in and of itself, a major intellectual challenge. Having to follow detailed citation and formatting guidelines as well may seem like just one more task to add to an already-too-long list of requirements.

Following these guidelines, however, serves several important purposes. First, it signals to your readers that your paper should be taken seriously as a student’s contribution to a given academic or professional field; it is the literary equivalent of wearing a tailored suit to a job interview. Second, it shows that you respect other people’s work enough to give them proper credit for it. Finally, it helps your reader find additional materials if he or she wishes to learn more about your topic.

Furthermore, producing a letter-perfect APA-style paper need not be burdensome. Yes, it requires careful attention to detail. However, you can simplify the process if you keep these broad guidelines in mind:

  • Work ahead whenever you can. Chapter 11 “Writing from Research: What Will I Learn?” includes tips for keeping track of your sources early in the research process, which will save time later on.
  • Get it right the first time. Apply APA guidelines as you write, so you will not have much to correct during the editing stage. Again, putting in a little extra time early on can save time later.
  • Use the resources available to you. In addition to the guidelines provided in this chapter, you may wish to consult the APA website at http://www.apa.org or the Purdue University Online Writing lab at http://owl.english.purdue.edu , which regularly updates its online style guidelines.

General Formatting Guidelines

This chapter provides detailed guidelines for using the citation and formatting conventions developed by the American Psychological Association, or APA. Writers in disciplines as diverse as astrophysics, biology, psychology, and education follow APA style. The major components of a paper written in APA style are listed in the following box.

These are the major components of an APA-style paper:

Body, which includes the following:

  • Headings and, if necessary, subheadings to organize the content
  • In-text citations of research sources
  • References page

All these components must be saved in one document, not as separate documents.

The title page of your paper includes the following information:

  • Title of the paper
  • Author’s name
  • Name of the institution with which the author is affiliated
  • Header at the top of the page with the paper title (in capital letters) and the page number (If the title is lengthy, you may use a shortened form of it in the header.)

List the first three elements in the order given in the previous list, centered about one third of the way down from the top of the page. Use the headers and footers tool of your word-processing program to add the header, with the title text at the left and the page number in the upper-right corner. Your title page should look like the following example.

Beyond the Hype: Evaluating Low-Carb Diets cover page

The next page of your paper provides an abstract , or brief summary of your findings. An abstract does not need to be provided in every paper, but an abstract should be used in papers that include a hypothesis. A good abstract is concise—about one hundred fifty to two hundred fifty words—and is written in an objective, impersonal style. Your writing voice will not be as apparent here as in the body of your paper. When writing the abstract, take a just-the-facts approach, and summarize your research question and your findings in a few sentences.

In Chapter 12 “Writing a Research Paper” , you read a paper written by a student named Jorge, who researched the effectiveness of low-carbohydrate diets. Read Jorge’s abstract. Note how it sums up the major ideas in his paper without going into excessive detail.

Beyond the Hype: Abstract

Write an abstract summarizing your paper. Briefly introduce the topic, state your findings, and sum up what conclusions you can draw from your research. Use the word count feature of your word-processing program to make sure your abstract does not exceed one hundred fifty words.

Depending on your field of study, you may sometimes write research papers that present extensive primary research, such as your own experiment or survey. In your abstract, summarize your research question and your findings, and briefly indicate how your study relates to prior research in the field.

Margins, Pagination, and Headings

APA style requirements also address specific formatting concerns, such as margins, pagination, and heading styles, within the body of the paper. Review the following APA guidelines.

Use these general guidelines to format the paper:

  • Set the top, bottom, and side margins of your paper at 1 inch.
  • Use double-spaced text throughout your paper.
  • Use a standard font, such as Times New Roman or Arial, in a legible size (10- to 12-point).
  • Use continuous pagination throughout the paper, including the title page and the references section. Page numbers appear flush right within your header.
  • Section headings and subsection headings within the body of your paper use different types of formatting depending on the level of information you are presenting. Additional details from Jorge’s paper are provided.

Cover Page

Begin formatting the final draft of your paper according to APA guidelines. You may work with an existing document or set up a new document if you choose. Include the following:

  • Your title page
  • The abstract you created in Note 13.8 “Exercise 1”
  • Correct headers and page numbers for your title page and abstract

APA style uses section headings to organize information, making it easy for the reader to follow the writer’s train of thought and to know immediately what major topics are covered. Depending on the length and complexity of the paper, its major sections may also be divided into subsections, sub-subsections, and so on. These smaller sections, in turn, use different heading styles to indicate different levels of information. In essence, you are using headings to create a hierarchy of information.

The following heading styles used in APA formatting are listed in order of greatest to least importance:

  • Section headings use centered, boldface type. Headings use title case, with important words in the heading capitalized.
  • Subsection headings use left-aligned, boldface type. Headings use title case.
  • The third level uses left-aligned, indented, boldface type. Headings use a capital letter only for the first word, and they end in a period.
  • The fourth level follows the same style used for the previous level, but the headings are boldfaced and italicized.
  • The fifth level follows the same style used for the previous level, but the headings are italicized and not boldfaced.

Visually, the hierarchy of information is organized as indicated in Table 13.1 “Section Headings” .

Table 13.1 Section Headings

A college research paper may not use all the heading levels shown in Table 13.1 “Section Headings” , but you are likely to encounter them in academic journal articles that use APA style. For a brief paper, you may find that level 1 headings suffice. Longer or more complex papers may need level 2 headings or other lower-level headings to organize information clearly. Use your outline to craft your major section headings and determine whether any subtopics are substantial enough to require additional levels of headings.

Working with the document you developed in Note 13.11 “Exercise 2” , begin setting up the heading structure of the final draft of your research paper according to APA guidelines. Include your title and at least two to three major section headings, and follow the formatting guidelines provided above. If your major sections should be broken into subsections, add those headings as well. Use your outline to help you.

Because Jorge used only level 1 headings, his Exercise 3 would look like the following:

Citation Guidelines

In-text citations.

Throughout the body of your paper, include a citation whenever you quote or paraphrase material from your research sources. As you learned in Chapter 11 “Writing from Research: What Will I Learn?” , the purpose of citations is twofold: to give credit to others for their ideas and to allow your reader to follow up and learn more about the topic if desired. Your in-text citations provide basic information about your source; each source you cite will have a longer entry in the references section that provides more detailed information.

In-text citations must provide the name of the author or authors and the year the source was published. (When a given source does not list an individual author, you may provide the source title or the name of the organization that published the material instead.) When directly quoting a source, it is also required that you include the page number where the quote appears in your citation.

This information may be included within the sentence or in a parenthetical reference at the end of the sentence, as in these examples.

Epstein (2010) points out that “junk food cannot be considered addictive in the same way that we think of psychoactive drugs as addictive” (p. 137).

Here, the writer names the source author when introducing the quote and provides the publication date in parentheses after the author’s name. The page number appears in parentheses after the closing quotation marks and before the period that ends the sentence.

Addiction researchers caution that “junk food cannot be considered addictive in the same way that we think of psychoactive drugs as addictive” (Epstein, 2010, p. 137).

Here, the writer provides a parenthetical citation at the end of the sentence that includes the author’s name, the year of publication, and the page number separated by commas. Again, the parenthetical citation is placed after the closing quotation marks and before the period at the end of the sentence.

As noted in the book Junk Food, Junk Science (Epstein, 2010, p. 137), “junk food cannot be considered addictive in the same way that we think of psychoactive drugs as addictive.”

Here, the writer chose to mention the source title in the sentence (an optional piece of information to include) and followed the title with a parenthetical citation. Note that the parenthetical citation is placed before the comma that signals the end of the introductory phrase.

David Epstein’s book Junk Food, Junk Science (2010) pointed out that “junk food cannot be considered addictive in the same way that we think of psychoactive drugs as addictive” (p. 137).

Another variation is to introduce the author and the source title in your sentence and include the publication date and page number in parentheses within the sentence or at the end of the sentence. As long as you have included the essential information, you can choose the option that works best for that particular sentence and source.

Citing a book with a single author is usually a straightforward task. Of course, your research may require that you cite many other types of sources, such as books or articles with more than one author or sources with no individual author listed. You may also need to cite sources available in both print and online and nonprint sources, such as websites and personal interviews. Chapter 13 “APA and MLA Documentation and Formatting” , Section 13.2 “Citing and Referencing Techniques” and Section 13.3 “Creating a References Section” provide extensive guidelines for citing a variety of source types.

Writing at Work

APA is just one of several different styles with its own guidelines for documentation, formatting, and language usage. Depending on your field of interest, you may be exposed to additional styles, such as the following:

  • MLA style. Determined by the Modern Languages Association and used for papers in literature, languages, and other disciplines in the humanities.
  • Chicago style. Outlined in the Chicago Manual of Style and sometimes used for papers in the humanities and the sciences; many professional organizations use this style for publications as well.
  • Associated Press (AP) style. Used by professional journalists.

References List

The brief citations included in the body of your paper correspond to the more detailed citations provided at the end of the paper in the references section. In-text citations provide basic information—the author’s name, the publication date, and the page number if necessary—while the references section provides more extensive bibliographical information. Again, this information allows your reader to follow up on the sources you cited and do additional reading about the topic if desired.

The specific format of entries in the list of references varies slightly for different source types, but the entries generally include the following information:

  • The name(s) of the author(s) or institution that wrote the source
  • The year of publication and, where applicable, the exact date of publication
  • The full title of the source
  • For books, the city of publication
  • For articles or essays, the name of the periodical or book in which the article or essay appears
  • For magazine and journal articles, the volume number, issue number, and pages where the article appears
  • For sources on the web, the URL where the source is located

The references page is double spaced and lists entries in alphabetical order by the author’s last name. If an entry continues for more than one line, the second line and each subsequent line are indented five spaces. Review the following example. ( Chapter 13 “APA and MLA Documentation and Formatting” , Section 13.3 “Creating a References Section” provides extensive guidelines for formatting reference entries for different types of sources.)

References Section

In APA style, book and article titles are formatted in sentence case, not title case. Sentence case means that only the first word is capitalized, along with any proper nouns.

Key Takeaways

  • Following proper citation and formatting guidelines helps writers ensure that their work will be taken seriously, give proper credit to other authors for their work, and provide valuable information to readers.
  • Working ahead and taking care to cite sources correctly the first time are ways writers can save time during the editing stage of writing a research paper.
  • APA papers usually include an abstract that concisely summarizes the paper.
  • APA papers use a specific headings structure to provide a clear hierarchy of information.
  • In APA papers, in-text citations usually include the name(s) of the author(s) and the year of publication.
  • In-text citations correspond to entries in the references section, which provide detailed bibliographical information about a source.

Writing for Success Copyright © 2015 by University of Minnesota is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License , except where otherwise noted.

documentation of research paper

Chapter 22 Appendix B: A Guide to Research and Documentation

Research documentation guidelines.

This appendix provides general guidelines for documenting researched information. See Chapter 7 "Researching" for more on the research process.

22.1 Choosing a Documentation Format

As a rule, your assignments requiring research will specify a documentation format. If you are free to use the style of your choice, you can choose any format you want as long as you are consistent, but you should know that certain disciplines tend to use specific documentation styles:

  • business and social sciences: American Psychological Association (APA)
  • natural and applied sciences: Council of Science Editors (CSE)
  • humanities: Modern Language Association (MLA) or the Chicago Manual of Style (CMS)

For the purposes of this appendix, we will confine ourselves to the three documentation formats that will be the most common in your undergraduate courses: the style manuals from APA and MLA, as well as CMS. (Other formats are listed at the end of this appendix. Also, note this appendix explains the “Notes-Bibliography” system of CMS, used more often in history, the arts, and humanities, rather than the “Author-Date” system, used in the sciences and social sciences.)

These three systems of documentation have been refined over many generations so that academics can rely on certain standards of attribution when they cite each other’s work and when their work is cited. When you enter into an academic conversation in a given discipline, it’s imperative that you play by its rules. It’s true that popular, nonacademic forms of attribution exist. Making a link to another website in a blog or a Twitter post works quite well, but in an academic context, such a form of attribution is not sufficient. Of course it should go without saying that stealing someone else’s words or borrowing them without attribution, whether you do it casually on the web or in an academic context, is simply wrong.

22.2 Integrating Sources

Your goal within a research paper is to integrate other sources smoothly into your paper to support the points you are making. As long as you give proper credit, you can ethically reference anyone else’s work. You should not, however, create a paper that is made up of one reference after another without any of your input. You should also avoid using half-page or whole-page quotations. Make sure to write enough of your material so that your sources are integrated into your work rather than making up the bulk of your paper.

Think of yourself as a kind of museum docent or tour guide when you are integrating sources into your work. You’ll usually want to take some time to set up your use of a source by placing it in a proper context. That’s why in most cases, before you even launch into quotation, paraphrase, or summary, you will have probably already used what’s called a “signal phrase” that identifies the author of the source, and often the specific publication (whether web or print) from which it is taken. After your use of the source, you’ll need to follow up with analysis and commentary on how you think it fits into the larger context of your argument.

22.3 Quoting, Paraphrasing, and Summarizing

When you quote another writer’s exact words, you will have to identify the page number within the source where you found the quotation or the paragraph number if the source is taken from an online format or database that does not indicate the original print pagination. Note that only APA allows the use of “p.” or “pp.”

Table 22.1 Citing Quotations

Paraphrased and summarized text is cited within text in the same way that quoted material is cited except that quotations are not used. In APA style, you do not need to include page numbers in this case, but MLA and CMS, on the other hand, do still require page numbers, when they are available.

Table 22.2 Citing Paraphrased or Summarized Text

22.4 Formatting In-Text References

When you use others’ ideas, you have a variety of options for integrating these sources into your text. The main requirement is that you make it clear within your in-text reference that the information is not yours and that you clearly indicate where you got the idea. The following box shows some alternate phrases for signaling that the ideas you are using belong to another writer. Using a variety of wording makes writing more interesting. Note: Past tense is used in these examples. You may elect to use present tense (“writes”) or past perfect tense (“has written”), but keep your tense use consistent.

Phrases That Signal an Idea Belongs to Another Writer (Shown in APA style)

  • According to Starr (2010)…
  • Acknowledging that…
  • Starr (2010) stated…
  • As Starr (2010) noted…
  • In 2010, Starr reported…
  • In the words of Starr (2010)…
  • It is obvious, according to Starr (2010), that…
  • Starr (2010) argued that…
  • Starr (2010) disagreed when she said…
  • Starr (2010) emphasized the importance of…
  • Starr (2010) suggested…
  • Starr observed in 2010 that…
  • Technology specialist, Linda Starr, claimed that…(2010).
  • …indicated Starr (2010).
  • …wrote Starr (2010)

Table 22.3 "Integrating Sources (Summarized or Paraphrased Ideas)" shows some actual examples of integrating sources within the guidelines of the three most common documentation formats. You should weave the cited details in with your ideas.

Table 22.3 Integrating Sources (Summarized or Paraphrased Ideas)

Table 22.4 Two Authors

Table 22.5 Multiple Authors

Table 22.6 Personal Communication

22.5 Developing a List of Sources

This appendix provides a general overview of some of the most common documentation guidelines for different types of sources. For situations not described in this appendix, such as types of sources not described in this chapter or situations where you elect to use footnotes or endnotes in addition to in-text, parenthetical citations, check the complete guidelines for the style you are using:

  • APA: http://www.apastyle.org
  • MLA: http://www.mla.org
  • CMS: http://www.chicagomanualofstyle.org

Some general online searches, especially those conducted on your library databases, are also likely to generate guidelines for a variety of documentation styles. Look for an opportunity to click on a “citation” or “documentation” icon, or ask a member of your college library staff for guidance. You can even get help through the word processing program you typically use. Microsoft Word, for instance, has an entire tab on the taskbar devoted to managing and documenting sources in all three of the styles featured here. Also, don’t forget the tip from Chapter 7 "Researching" about the free resources that abound on the web from various online writing labs (OWLs) managed by writing programs at colleges and universities across the country.

Each different documentation style has its own set of guidelines for creating a list of references at the end of the essay (called “works cited” in MLA, “references” in APA, and “bibliography” in CMS). This section includes citations for the sources included in other parts of this appendix. For additional citation styles, consult complete citation guidelines for the style you are using.

Source lists should always be in alphabetical order by the first word of each reference, and you should use hanging indentation (with the first line of each reference flush with the margin and subsequent lines indented one-half inch). Here are some of the most common types of entries you will be using for your references at the end of your research essays. These lists are by no means exhaustive, but you will note from the examples some of the most important differences in conventions of punctuation, font, and the exact content of each style.

Table 22.7 APA References

Table 22.8 MLA Works Cited

Table 22.9 CMS Bibliography

22.6 Using Other Formats

Although APA, MLA, and Chicago are the most widely used documentation styles, many other styles are used in specific situations. Some of these other styles are listed in Table 22.10 "Other Documentation Formats" . You can find more about them by searching online.

Table 22.10 Other Documentation Formats

News alert: UC Berkeley has announced its next university librarian

Secondary menu

  • Log in to your Library account
  • Hours and Maps
  • Connect from Off Campus
  • UC Berkeley Home

Search form

How to write good documentation: home, documentation.

documentation of research paper

Why to Write Documentation

Documentation effectively connects humans and machines.

Why writing documentation is important:

  • You will be using your code in 6 months
  • You want people to use your code and give you credit
  • You want to learn self-determination
  • Others would be encouraged to contribute to your code
  • Others can easily use your code and build upon it
  • Advance the science
  • Encourage open science 
  • Allow reproducibility and transparency

What should you document about your research? Everything! All the data, notes, code, and materials someone else would need to reproduce your work.

Consider the following questions:

  • How is your data gathered?
  • What variables did you use?
  • Did you use any code to clean/analyze your data?

Best Practices for Documenting Your Project

Best Practices for Writing Documentation:

  • A brief description of the project
  • Installation instructions
  • A short example/tutorial
  • Allow issue tracker for others
  • What a function does
  • What are the function's parameters or arguments are
  • What a function returns
  • Document your code
  • Apply coding conventions, such as file organization, comments, naming conventions, programming practices, etc.
  • Include information for contributors
  • Include citation information
  • Include licensing information
  • Link to your e-mail address at the end
  • List all the versions of the files along with the major edits you did in each version

An important tip: Naming files should be descriptive and consistent!

  • Date format (ISO 8601 Standard): YYYYMMDDThhmmss
  • Project or experiment name
  • Researcher name/initials
  • Date or date range of collection version

An example for README file.

documentation of research paper

An example of code documentation.

documentation of research paper

Tools for Documentation

Tools for Documentation:

  • Doctest  
  • R Markdown  
  • Doxygen  - Doxygen can be used for C, C#, PHP, Java, Python, and Fortran.
  • ​ BoostBook

Software Documentation Hosting Options:

  • Read The Docs
  • 18 Software Documentation Tools
  • BIDS Docathon Kickoff - A Video
  • Docathon at BIDS
  • Documenting Your Code
  • First Steps with Sphinx
  • Google Style Guides
  • How to maintain an open source project
  • A Quick Guide to Software Licensing for the Scientist-Programmer

documentation of research paper

Library Data Services Program

  • Last Updated: Nov 6, 2023 2:10 PM
  • URL: https://guides.lib.berkeley.edu/how-to-write-good-documentation

About Documentation Styles

What are documentation styles.

A documentation style is a standard approach to the citation of sources that the author of a paper has consulted, abstracted, or quoted from. It prescribes methods for citing references within the text, providing a list of works cited at the end of the paper, and even formatting headings and margins.

Different academic disciplines use different documentation styles; your instructor may require you to use a particular style, or may allow you use one of your choosing.

It is important to fully understand the documentation style to be used in your paper, and to apply it consistently.

Furthermore, documentation styles allow you to give credit for secondary sources you have used in writing your paper.

Citing sources not only gives credit where it’s due, but also allows your reader to locate the sources you have consulted. In short, the reader of your paper must be able to use the information you provide, both in the text and in appended list(s), to duplicate the research you have done.

What do I need to document?

In general, you must document information that originates in someone else’s work. All of the following should be accompanied by a reference to the original:

  • Direct quotations
  • Paraphrases and summaries
  • Information and ideas that are not common knowledge or are not available in a standard reference work
  • Any borrowed material that might appear to be your own if there were no citation

By now you’re likely wondering, “Yes, but how do I know where the ideas of others end and my own begin?” If you’re writing papers that require research, you’ve probably been in academia long enough to know that the only good answer to such a question is, “Good question.”

Giving credit where it’s due is a founding principle of academic inquiry, one that fosters the free exchange of ideas. Ultimately, you’ll need to decide for yourself which ideas you can claim as your own and which should be attributed to others. Perhaps we should consider how we’d like our work to be credited, and use that as our guide.

How should I gather information for documenting sources?

You can make the process of applying any documentation style easier if you keep good notes while you perform research.

Write down the most complete bibliographic information available for each source that you consult; you may want to take a look at the sample references list for the style you will be using to get an idea of the amount of detail that’s required. If you write out quotations or data from a source, be sure to note the number of the page(s) on which the information appears in the original. Double check the quotation for accuracy before you return the source to the library.

It’s a good idea to put citations into your paper as you draft it. When you quote, put the source and page number directly after, perhaps marked with asterisks. When you refer, do the same. And when you place a citation in your text, add the source to your working bibliography.

When it comes time to put the finishing touches on your paper, the information you need will be available right in your text, and may be easily put into the proper format.

Which style should I use?

Choosing the appropriate documentation style for your paper may depend on three factors:

  • The requirements of the particular course;
  • The standard for the discipline in which you are studying; or
  • Your individual preference.

Documentation style required for a course

Your instructor may assign a documentation style for papers to be written for that course. This will often be indicated on the course syllabus or in the paper assignment, but may simply be mentioned during class. If no documentation style is prescribed, you should ask whether the instructor has a preference. If no preference is indicated, then you are free to choose a style.

Documentation style used in a discipline

In doing so, consider which style will be most appropriate for your area of specialization. If you are pursuing a major in the humanities, consider learning the MLA style. If behavioral or social sciences are likely to be your interest, then the APA style may be most appropriate. For information about the major documentation styles, click on one of the menu items on the Documentation styles page.

Documentation style based on individual preference

If you don’t know what you want to major in, or aren’t particularly interested in adopting a documentation style that will last your whole life long, then what you should do is read the Writing Center Review of Documentation styles, where we compare the distinguishing features of the most commonly used documentation styles. Take a look around, choose a style that fits your style, and then go to its pages to learn how to use it.

This is an accordion element with a series of buttons that open and close related content panels.

Cite References in Your Paper

American Psychological Association Documentation

Chicago/Turabian Documentation

Modern Language Association Documentation

American Political Science Association Documentation

Council of Science Editors Documentation

Institute of Electrical and Electronics Engineers

Numbered References

Quoting and Paraphrasing Sources

  • Skip to main content
  • Skip to ChatBot Assistant
  • Academic Writing
  • What is a Research Paper?
  • Steps in Writing a Research Paper
  • Critical Reading and Writing
  • Punctuation
  • Writing Exercises
  • ELL/ESL Resources

Documenting Sources

Documenting means showing where you got source information that's not your own. Remember, a research paper blends your ideas with ideas and information from other sources. Documentation shows the reader what ideas are yours and what information and ideas you've taken from a source to support your point of view.

Why Document?

  • By correctly documenting, you establish your credibility as a writer and researcher. You're letting your reader know that you've consulted experts whose ideas and information back up your own thoughts and ideas. Consequently, you make your viewpoint or argument more believable.
  • When you don't document correctly, your academic integrity can be called into question, because it may seem as though you're passing off others' ideas as your own.
  • If you don't document, you could inadvertently plagiarize, which is grounds for dismissal from college.

Academic Integrity

Academic integrity involves not only acknowledging your sources, but also creating your own ideas. Academic integrity, explained in this way, sounds relatively simple. But the particular applications are a bit more tricky. The most common academic integrity problems that most students encounter are these:

  • relying too heavily on others' information in a research paper
  • relying too heavily on others' words in a paraphrase or summary
  • citing and documenting sources incorrectly
  • relying too heavily on help from other sources

The most egregious violation of academic integrity is when a student uses a writing assignment for more than one course, or when a student "borrows" a paper and passes it off as his or her own work.

What to Document

The basic rule for documentation is this: Document any specific ideas, opinions, and facts that are not your own. The only thing you don't have to document is common knowledge.

For example: you do have to document the fact that 103 cities in New York state were originally settled by English settlers because this is a specific fact that is not common knowledge. You do not have to document the information that New York state has places named for British cities, since this is common knowledge.

There are two categories of common knowledge:

  • information that's known to the general public
  • information that is agreed upon by most people in a professional field

Tip: Sometimes common knowledge can be tricky to define. A good rule is this: if in doubt, document.

Can You Document Too Much?

If you find yourself needing to document almost every sentence, then it means you have not thought enough about your topic to develop your own ideas. A paper should not be just a collection of others' ideas and facts. Sources should only support or substantiate your ideas.

Tip:  The rule of thumb is that whenever you use information from sources you should comment on the information. Your comment should be approximately the same length as the source itself.

Where to Document

You must identify your sources in two places in your research paper:

  • in your paper as you use direct quotations or paraphrases and summaries of ideas and information from the sources you've researched

Citing at the end of the paper: Put your notecards with the source information on them in alphabetical order according to the authors' last names, then follow the correct format for providing the essential source information.

Documenting your sources within the text of your paper:   Most current research papers insert the basic source information inside parentheses within the text of the paper either at the end of the sentence, or group of sentences, that contain the source's information.

Tip:  Footnotes are out of date.

Merely documenting paraphrases and summaries at the end of paragraphs leaves your reader confused. Does the documentation refer to the last sentence? the whole paragraph? part of a paragraph? So you also need to show where the source's information starts as well as ends. The easiest way to do this is to use a phrase such as "According to Dr. James Watts …" or "Carly Simon maintains that…"

According to the "American Heritage Dictionary," plagiarism means "to steal and use [the ideas and writings of another] as one's own. To appropriate passages or ideas from [another] and use them as one's own."

Plagiarism is a serious offense within the academic community. You plagiarize whether you intend to or not when you don't credit others' ideas within/at the end of your paper. Even though you may have rewritten ideas and information using your own words in a paraphrase or summary, the ideas and information are not yours. You must cite your source.

Read more information about plagiarism .

Need Assistance?

If you would like assistance with any type of writing assignment, learning coaches are available to assist you. Please contact Academic Support by emailing [email protected].

Questions or feedback about SUNY Empire's Writing Support?

Contact us at [email protected] .

Smart Cookies

They're not just in our classes – they help power our website. Cookies and similar tools allow us to better understand the experience of our visitors. By continuing to use this website, you consent to SUNY Empire State University's usage of cookies and similar technologies in accordance with the university's Privacy Notice and Cookies Policy .

Documentation in Reports and Research Papers

  • An Introduction to Punctuation
  • Ph.D., Rhetoric and English, University of Georgia
  • M.A., Modern English and American Literature, University of Leicester
  • B.A., English, State University of New York

In a report or  research paper , documentation is the evidence  provided for information and ideas borrowed from others. That evidence includes both primary sources  and secondary sources .

There are numerous documentation styles and formats, including MLA style (used for research in the humanities), APA style (psychology, sociology, education), Chicago style (history), and ACS style (chemistry).

Examples and Observations

  • Adrienne Escoe "Documentation has many meanings, from the broad—anything written in any medium—to the narrow—policies and procedures manuals or perhaps records." ( T he Practical Guide to People-Friendly Documentation , 2nd. ed. ASQ Quality Press, 2001)
  • Kristin R. Woolever "An issue more important than documentation form is knowing when to document. In brief, anything that is copied needs to be documented... "Perhaps the best tip for knowing when to document is to use common sense. If writers are careful to give credit where it is due and to provide the reader with easy access to all the source material, the text is probably documented appropriately." ( About Writing: A Rhetoric for Advanced Writers . Wadsworth, 1991)

Note-Taking and Documentation During the Research Process

  • Linda Smoak Schwartz "The most important thing to remember when you take notes from your sources is that you must clearly distinguish between quoted, paraphrased , and summarized material that must be documented in your paper and ideas that do not require documentation because they are considered general knowledge about that subject." ( The Wadsworth Guide to MLA Documentation , 2nd ed. Wadsworth, 2011)

Library Resources Versus Internet Resources

  • Susan K. Miller-Cochran and Rochelle L. Rodrigo "When you are reviewing and analyzing your resources, keep in mind that the library/Internet distinction is not quite as simple as it might seem at first. The Internet is where students often turn when they are having difficulty getting started. Many instructors warn students against using Internet resources because they are easily alterable and because anyone can construct and publish a Web site. These points are important to remember, but it is essential to use clear evaluative criteria when you are looking at any resource. Print resources can be self-published as well. Analyzing how easily a resource is changed, how often it is changed, who changed it, who reviews it, and who is responsible for the content will help you choose resources that are reliable and credible, wherever you might find them." ( The Wadsworth Guide to Research, Documentation , rev. ed. Wadsworth, 2011)

Parenthetical Documentation

  • Joseph F. Trimmer "You may decide to vary the pattern of documentation by presenting the information from a source and placing the author's name and page number in parentheses at the end of the sentence. This method is particularly useful if you have already established the identity of your source in a previous sentence and now want to develop the author's idea in some detail without having to clutter your sentences with constant references to his or her name.​" ( A Guide to MLA Documentation , 9th ed. Wadsworth, 2012)
  • Meaning of Tense Shift in Verbs
  • What Is a Research Paper?
  • Secondary Sources in Research
  • What Is a Primary Source?
  • Primary and Secondary Sources in History
  • An Introduction to Academic Writing
  • What Is a Citation?
  • Bibliography: Definition and Examples
  • How to Develop a Research Paper Timeline
  • What Is a Style Guide and Which One Do You Need?
  • How to Use Libraries and Archives for Research
  • How to Write a Research Paper That Earns an A
  • Finding Sources for Death Penalty Research
  • Writing a Paper about an Environmental Issue
  • What Is a Bibliography?
  • How to Use Footnotes in Research Papers
  • U.S. Locations
  • UMGC Europe
  • Learn Online
  • Find Answers
  • 855-655-8682
  • Current Students

Online Guide to Writing and Research

Academic integrity and documentation, explore more of umgc.

  • Online Guide to Writing

Types of Documentation

The two most common types of documentation used in research are note citations and parenthetical citations (Winkler & McCuen-Metherell, 2008, p. 4).  You might also see terms like “footnotes,” “endnotes,” or “references” when learning about documentation practices. Refer to the required style guide and your instructor when determining exactly what kind of documentation is required for your assignment.

Mailing Address: 3501 University Blvd. East, Adelphi, MD 20783 This work is licensed under a  Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License . © 2022 UMGC. All links to external sites were verified at the time of publication. UMGC is not responsible for the validity or integrity of information located at external sites.

Table of Contents: Online Guide to Writing

Chapter 1: College Writing

How Does College Writing Differ from Workplace Writing?

What Is College Writing?

Why So Much Emphasis on Writing?

Chapter 2: The Writing Process

Doing Exploratory Research

Getting from Notes to Your Draft

Introduction

Prewriting - Techniques to Get Started - Mining Your Intuition

Prewriting: Targeting Your Audience

Prewriting: Techniques to Get Started

Prewriting: Understanding Your Assignment

Rewriting: Being Your Own Critic

Rewriting: Creating a Revision Strategy

Rewriting: Getting Feedback

Rewriting: The Final Draft

Techniques to Get Started - Outlining

Techniques to Get Started - Using Systematic Techniques

Thesis Statement and Controlling Idea

Writing: Getting from Notes to Your Draft - Freewriting

Writing: Getting from Notes to Your Draft - Summarizing Your Ideas

Writing: Outlining What You Will Write

Chapter 3: Thinking Strategies

A Word About Style, Voice, and Tone

A Word About Style, Voice, and Tone: Style Through Vocabulary and Diction

Critical Strategies and Writing

Critical Strategies and Writing: Analysis

Critical Strategies and Writing: Evaluation

Critical Strategies and Writing: Persuasion

Critical Strategies and Writing: Synthesis

Developing a Paper Using Strategies

Kinds of Assignments You Will Write

Patterns for Presenting Information

Patterns for Presenting Information: Critiques

Patterns for Presenting Information: Discussing Raw Data

Patterns for Presenting Information: General-to-Specific Pattern

Patterns for Presenting Information: Problem-Cause-Solution Pattern

Patterns for Presenting Information: Specific-to-General Pattern

Patterns for Presenting Information: Summaries and Abstracts

Supporting with Research and Examples

Writing Essay Examinations

Writing Essay Examinations: Make Your Answer Relevant and Complete

Writing Essay Examinations: Organize Thinking Before Writing

Writing Essay Examinations: Read and Understand the Question

Chapter 4: The Research Process

Planning and Writing a Research Paper

Planning and Writing a Research Paper: Ask a Research Question

Planning and Writing a Research Paper: Cite Sources

Planning and Writing a Research Paper: Collect Evidence

Planning and Writing a Research Paper: Decide Your Point of View, or Role, for Your Research

Planning and Writing a Research Paper: Draw Conclusions

Planning and Writing a Research Paper: Find a Topic and Get an Overview

Planning and Writing a Research Paper: Manage Your Resources

Planning and Writing a Research Paper: Outline

Planning and Writing a Research Paper: Survey the Literature

Planning and Writing a Research Paper: Work Your Sources into Your Research Writing

Research Resources: Where Are Research Resources Found? - Human Resources

Research Resources: What Are Research Resources?

Research Resources: Where Are Research Resources Found?

Research Resources: Where Are Research Resources Found? - Electronic Resources

Research Resources: Where Are Research Resources Found? - Print Resources

Structuring the Research Paper: Formal Research Structure

Structuring the Research Paper: Informal Research Structure

The Nature of Research

The Research Assignment: How Should Research Sources Be Evaluated?

The Research Assignment: When Is Research Needed?

The Research Assignment: Why Perform Research?

Chapter 5: Academic Integrity

Academic Integrity

Giving Credit to Sources

Giving Credit to Sources: Copyright Laws

Giving Credit to Sources: Documentation

Giving Credit to Sources: Style Guides

Integrating Sources

Practicing Academic Integrity

Practicing Academic Integrity: Keeping Accurate Records

Practicing Academic Integrity: Managing Source Material

Practicing Academic Integrity: Managing Source Material - Paraphrasing Your Source

Practicing Academic Integrity: Managing Source Material - Quoting Your Source

Practicing Academic Integrity: Managing Source Material - Summarizing Your Sources

Types of Documentation: Bibliographies and Source Lists

Types of Documentation: Citing World Wide Web Sources

Types of Documentation: In-Text or Parenthetical Citations

Types of Documentation: In-Text or Parenthetical Citations - APA Style

Types of Documentation: In-Text or Parenthetical Citations - CSE/CBE Style

Types of Documentation: In-Text or Parenthetical Citations - Chicago Style

Types of Documentation: In-Text or Parenthetical Citations - MLA Style

Types of Documentation: Note Citations

Chapter 6: Using Library Resources

Finding Library Resources

Chapter 7: Assessing Your Writing

How Is Writing Graded?

How Is Writing Graded?: A General Assessment Tool

The Draft Stage

The Draft Stage: The First Draft

The Draft Stage: The Revision Process and the Final Draft

The Draft Stage: Using Feedback

The Research Stage

Using Assessment to Improve Your Writing

Chapter 8: Other Frequently Assigned Papers

Reviews and Reaction Papers: Article and Book Reviews

Reviews and Reaction Papers: Reaction Papers

Writing Arguments

Writing Arguments: Adapting the Argument Structure

Writing Arguments: Purposes of Argument

Writing Arguments: References to Consult for Writing Arguments

Writing Arguments: Steps to Writing an Argument - Anticipate Active Opposition

Writing Arguments: Steps to Writing an Argument - Determine Your Organization

Writing Arguments: Steps to Writing an Argument - Develop Your Argument

Writing Arguments: Steps to Writing an Argument - Introduce Your Argument

Writing Arguments: Steps to Writing an Argument - State Your Thesis or Proposition

Writing Arguments: Steps to Writing an Argument - Write Your Conclusion

Writing Arguments: Types of Argument

Appendix A: Books to Help Improve Your Writing

Dictionaries

General Style Manuals

Researching on the Internet

Special Style Manuals

Writing Handbooks

Appendix B: Collaborative Writing and Peer Reviewing

Collaborative Writing: Assignments to Accompany the Group Project

Collaborative Writing: Informal Progress Report

Collaborative Writing: Issues to Resolve

Collaborative Writing: Methodology

Collaborative Writing: Peer Evaluation

Collaborative Writing: Tasks of Collaborative Writing Group Members

Collaborative Writing: Writing Plan

General Introduction

Peer Reviewing

Appendix C: Developing an Improvement Plan

Working with Your Instructor’s Comments and Grades

Appendix D: Writing Plan and Project Schedule

Devising a Writing Project Plan and Schedule

Reviewing Your Plan with Others

By using our website you agree to our use of cookies. Learn more about how we use cookies by reading our  Privacy Policy .

Grad Coach (R)

What’s Included: Research Paper Template

If you’re preparing to write an academic research paper, our free research paper template is the perfect starting point. In the template, we cover every section step by step, with clear, straightforward explanations and examples .

The template’s structure is based on the tried and trusted best-practice format for formal academic research papers. The template structure reflects the overall research process, ensuring your paper will have a smooth, logical flow from chapter to chapter.

The research paper template covers the following core sections:

  • The title page/cover page
  • Abstract (sometimes also called the executive summary)
  • Section 1: Introduction 
  • Section 2: Literature review 
  • Section 3: Methodology
  • Section 4: Findings /results
  • Section 5: Discussion
  • Section 6: Conclusion
  • Reference list

Each section is explained in plain, straightforward language , followed by an overview of the key elements that you need to cover within each section. We’ve also included links to free resources to help you understand how to write each section.

The cleanly formatted Google Doc can be downloaded as a fully editable MS Word Document (DOCX format), so you can use it as-is or convert it to LaTeX.

FAQs: Research Paper Template

What format is the template (doc, pdf, ppt, etc.).

The research paper template is provided as a Google Doc. You can download it in MS Word format or make a copy to your Google Drive. You’re also welcome to convert it to whatever format works best for you, such as LaTeX or PDF.

What types of research papers can this template be used for?

The template follows the standard best-practice structure for formal academic research papers, so it is suitable for the vast majority of degrees, particularly those within the sciences.

Some universities may have some additional requirements, but these are typically minor, with the core structure remaining the same. Therefore, it’s always a good idea to double-check your university’s requirements before you finalise your structure.

Is this template for an undergrad, Masters or PhD-level research paper?

This template can be used for a research paper at any level of study. It may be slight overkill for an undergraduate-level study, but it certainly won’t be missing anything.

How long should my research paper be?

This depends entirely on your university’s specific requirements, so it’s best to check with them. We include generic word count ranges for each section within the template, but these are purely indicative. 

What about the research proposal?

If you’re still working on your research proposal, we’ve got a template for that here .

We’ve also got loads of proposal-related guides and videos over on the Grad Coach blog .

How do I write a literature review?

We have a wealth of free resources on the Grad Coach Blog that unpack how to write a literature review from scratch. You can check out the literature review section of the blog here.

How do I create a research methodology?

We have a wealth of free resources on the Grad Coach Blog that unpack research methodology, both qualitative and quantitative. You can check out the methodology section of the blog here.

Can I share this research paper template with my friends/colleagues?

Yes, you’re welcome to share this template. If you want to post about it on your blog or social media, all we ask is that you reference this page as your source.

Can Grad Coach help me with my research paper?

Within the template, you’ll find plain-language explanations of each section, which should give you a fair amount of guidance. However, you’re also welcome to consider our private coaching services .

Free Webinar: Literature Review 101

  • View source

documentation of research paper

  • Recent Changes
  • Random Page
  • What links here
  • Related changes
  • Special pages
  • Printable version
  • Permanent link
  • Page information

Research Documentation

When publishing research , it is important to make documentation available so that readers can understand the details of the research design that the work reports. This includes all of the technical details and decisions that could influence how the findings are read or understood. Usually, this will involve producing a document along the lines of a methodological note or appendix. That document will describe how a given study was designed and how the design was carried out. The level of detail is in such a document should be relatively high. This page will describe some common approaches to compiling this kind of material and retaining the needed information in an organized fashion throughout the life of a research project.

  • Research documentation provides the context to understanding the results of a given research output.
  • There is no standard form for this documentation, and its location and format will depend on the type of research output produced.
  • For academic materials, this documentation often takes the form of a structured methodological appendix.
  • For policy outputs or online products, it may be appropriate to include an informative README webpage or document.
  • The most important process for preparing this documentation will be retaining and organizing the needed information throughout the life of the project, so that the team will not have to search through communications or data archives for small details at publication time.

What to include in research documentation

Research documentation should include all the information that is needed to understand the underlying design for the research output. This can include descriptions of:

  • Populations of interest that informed the study
  • Methods of sampling or other sources of data about selecting the units of observation that were actually included in the study
  • Power calculations and pre-analysis plans
  • Field work, including data collection or experimental manipulation, such as study protocols and monitoring or quality assurance information
  • Data collection tools such as survey instruments, search keywords, and instructions or code for API requests or database queries
  • Statistical approaches such as definitions of key constructed indicators, corrections or adjustments to data, and precise definitions of estimators and estimation procedures
  • Data completeness, including non-observed units or quantities that were planned or "tracking" information

All of the research documentation taken together should broadly allow a reader to understand how information was gathered, what it represents, what kind of information and data files to expect, and how to relate that information to the results of the research. Research documentation is not a complete guide to data, however; it does not need to provide the level of detail or instructions that would enable a reader to approach different research questions using the same data.

Documentation will take different forms depending on the information included. Much of it will be written narrative rather than, for example, formal datasets . Understanding research documentation should not require the user to have any special software or to undertake any analytical tasks themselves. Relevant datasets (such as tracking of units of observation over time) might be included alongside the documentation, but the documentation should summarize in narrative form all the information from that dataset that is likely to affect the interpretation of the research.

Structuring research documentation as a publication appendix

If you are preparing documentation to accompany the publication of an academic output such as a working paper or journal article, the most common form of research documentation is a structured supplemental appendix. Check the journal's publication process for details. Some publishers allow unlimited supplementary materials to be included in a format such as an author-created document. These materials may or may not be included under the peer review of the main manuscript and might only be intended to provide context for readers and reviewers. In this case you should provide complete information in that material. Other publishers expect all supplementary materials to be read and reviewed as part of the publication process. In this case you should provide the minimum additional detail required to understand the research here (since much of the appendix will likely be taken up by supplementary results rather than documentation), and consider other methods for releasing complete documentation, such as self-publication on OSF or Zenodo.

Since there is unlimited space and you may have a large amount of material to include in a documentation appendix, organization is essential. It is appropriate to have several appendices that cover different aspects of the research. For example, Appendix A may include information about the study population and data, such as the total number of units available for observation , the number selected or included for observation, the number successfully included, and descriptive statistics about subgroups, strata, clusters, or other units relevant to the research. It could be accompanied by a tracking dataset with full information about the process. Appendix B might include information about an intended experimental manipulation in one section, and information about implementation, take-up, and fidelity in a second section. It could be accompanied by a dataset with key indicators. Appendix C might include data collection protocols and definitions of constructed variables and comparisons with alternative definitions, and be accompanied by data collection instruments and illustrative figures. Each appendix should included relevant references. Supplementary exhibits should be numbered to correspond with the appendix they pertain to. More granular appendices are generally preferable so that referencing and numbering remains relatively uncomplicated.

There have been many attempts to standardized some of these elements, such as the STROBE and CONSORT reporting checklists . Journals will let you know if they expect these exact templates to be followed. Even if they are not required, such templates can still be used directly or to provide inspiration or structure for the materials you might want to include.

The Sheridan Libraries

  • Documenting Research Data
  • Sheridan Libraries
  • Code Documentation
  • Introduction
  • Metadata and Metadata Standards
  • Tabular Data Documentation
  • Medical Research Metadata
  • Geospatial Data Documentation

Data Services Profile

documentation of research paper

We are here to help you find, use, manage, visualize and share your data. Contact us  to schedule a consultation. View and register for upcoming workshops . Visit our website to learn more about our services.

Best Practices for Code Documentation

General guidelines and best practices for documenting code:

A Guide to Reproducible Code in Ecology and Evolution : A guide to write reproducible code for researchers in Ecology and Evolution fields, created by  British Ecological Society . Most guidelines can still be applied to other disciplines.  

Best Practices for Scientific Computing : This article is published in PLoS Biology in 2014 and offers several useful best practices for writing reproducible code.   

Style Guides

Guides for R and Python syntax and styles: 

The tidyverse style guide : This style guide is created by Hadley Wickham for R programming language. There are two R packages,  styler  and  lintr , that support this style guide.  

Google’s R style guide : This style guide is a fork from  the tidyverse style guide  above. Google modified it with its internal R user community.     

PEP8 style guide for python code : A style guide for writing Python code on Python’s official website.  

Google’s Python style guides : The style guide created by Google for Python programming language. It is a list of dos and don’ts when programming in Python.  

Write Comments

Tutorials and templates for writing helpful code comments: 

Code Like a Pro:  Comments | How to Write Code Professionally  (With Code Examples): An YouTube video shows how to write good comments for code and how to give good variable/function names so the code is self-explanatory.  

Putting comments in code: the good, the bad and the ugly : An article that discuss documentation comments and clarification comments. 

Choose an open source license for code : Visit this website to view different types of software license and choose one most appropriate for your code. 

My easy R script header template : A R script template with header information and instructions for how to use this template.   

A Python script to create a header for Python scripts : A Python script that can create a header for your own Python scripts. 

Jim's Computer Science Topics  –  Commenting Your Code : A professor, H. James de St. Germain, in the School of Computing, University of Utah created these materials for his computer science course students. The programming languages used in examples are Matlab, C, and Actionscript. 

Writing Comments in Python  (Guide): A guide on  Real Python  about how to write comments for Python code.   

R Markdown is a file format to create interactive documents in R. Such a document can include text,  code chunks and metadata. Other programming languages, such as Python, SQL, D3, can also be documented with R Markdown. 

R Markdown official site :   The office site for R Markdown, with instructions to get started, and gallery, resources to learn more.   

RPubs :  A web space to share R Markdown documents, created by  RStudio . You can also view other people’s R Markdown documents.   

R Markdown: The Definitive Guide : A book written by the creator of R Markdown package,  Yihui Xie . A good reference when writing an R Markdown document.   

R Markdown chapter  in R for Data Science: An R Markdown chapter in the  R for Data Science  book, written by Hadley Wickham and Garrett Grolemund. 

Introduction to R Markdown : A section about R Markdown in  Reproducible Research course  created by  National Bioinformatics Infrastructure Sweden (NBIS) .  

An R and R Markdown Tutorial : A step-by-step instruction to create an R project and an R Markdown document. This is shared on  RPubs .  

Pimp my RMD: a few tips for R Markdown : This is not a guide for how to write an R Markdown document, but some useful tips to improve the appearance of output documents.  

Jupyter Notebooks

Jupyter Notebook allows you to create interactive documents in Python. You can embed and execute code within Jupyter Notebooks. Other programming languages, such as R and Julia, can be documented with Jupyter Notebooks as well.  

Jupyter Notebook official site : The official site for Project Jupyter, including documentation, a list of Jupyter community,  nbviewer  for viewing and sharing Jupyter Notebook and the latest information about Project Jupyter.  

Jupyter Notebook: An Introduction  by Real Python: A brief introduction of Jupyter Notebook, including how to get started, elements in a Jupyter Notebook, how to explore a Notebook and Notebook extensions.  

Jupyter Notebook Tutorial: The Definitive Guide  by Data Camp: A tutorial introduces the history of Jupyter Notebook, and how to install, use and create a Notebook document. In addition, it offers tips, best practices and examples of Jupyter Notebook.   

A gallery of interesting Jupyter Notebooks : A list of Jupyter Notebook examples in various disciplines on GitHub. 

Ten simple rules for writing and sharing computational analyses in Jupyter Notebooks : A journal article on PLoS Computational Biology. It provides 10 rules to best sharing data anlaysis in Jupyter Notebooks.  

Guide for Reproducible Research and Data Science in Jupyter Notebooks : A crowdsourced guidelines and tutorials on GitHub for reproducible research in Jupyter Notebooks.    

Best practices and templates for creating a well-structured ReadMe file:  

Choose an open source license for code : Visit this website to view different types of software license and choose one most appropriate for your code. 

How to cite and describe software : Tips to describe and cite software you have used or built your code upon.  

ReadMe 101 : Explain what is a ReadMe file and why you need to create one. Provide several suggestions for a good ReadMe and also a couple templates.   

Art of ReadMe and examples : Provide some best practices tips for creating a good ReadMe, with several examples of ReadMe and a ReadMe checklist. 

A good readme template by PurpleBooth : A good ReadMe template for  GitHub  users. 

A readme template by scottydocs : Another good ReadMe template on GitHub.

Computational physics ReadMe template : A ReadMe template on  GitLab  for researchers work in computational physics field, but could also be expanded to other fields.  

Version Control and Code Repository

Introduction of version control system, why it is important and best practices for version control. In addition, some resources about Git, GitHub and GitHub Desktop including installation instructions, documentation and tutorials. 

Source code management : A tutorial created by  BitBucket  about the importance of source code management, and the benefits and best practices of it.  

Version control concepts and best practices : Professor  Michael Ernst  in the Department of Computer Science & Engineering, University of Washington created this as an introduction to version control concepts and best practices tips for versioning. 

About version control: An introduction to different version control systems on the Git's official site. 

Comparison of centralized and distributed version control systems:

Evolution of version control system

Comparison of version control system tools

The Wikipedia page that compare multiple version control systems

The Git official site : The official site of Git. You can download the latest release version of Git and find documentation and other related information here. 

GitHub Desktop  installation  and  documentation : GitHub Desktop is a graphic user interface (GUI) tool that you can use to interact with GitHub repositories from a local computer.  Here are installation instructions and documentation for how to use GitHub Desktop. 

Git & GitHub Crash Course For Beginners : An YouTube tutorial shows how to install Git and use command lines to do version control.  

GitHub Guides : Online guides for using some basic features of GitHub.  

Happy Git and GitHub for the useR : An online book about how to use Git and GitHub for R users. You will learn how to connect git, GitHub and RStudio.  

GitHub Learning Lab : Many interactive, hands-on tutorials for GitHub learners.    

Resources to learn Git :  A few of resources to learn Git.    

Git and GitHub learning resources : A list of Git and GitHub learning resources in GitHub Documentation. 

  • << Previous: Tabular Data Documentation
  • Next: Medical Research Metadata >>
  • Last Updated: Mar 8, 2024 11:03 AM
  • URL: https://guides.library.jhu.edu/documenting_data

U.S. flag

An official website of the United States government

The .gov means it’s official. Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

The site is secure. The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

  • Publications
  • Account settings

Preview improvements coming to the PMC website in October 2024. Learn More or Try it out now .

  • Advanced Search
  • Journal List
  • Scientific Reports

Logo of scirep

Documenting research software in engineering science

Sibylle hermann.

1 Institute of Engineering and Computational Mechanics, University of Stuttgart, 70569 Stuttgart, Germany

2 Cluster of Excellence SimTech, University of Stuttgart, 70569 Stuttgart, Germany

Jörg Fehr

The reuse of research software needs good documentation, however, the documentation in particular is often criticized. Especially in non-IT specific disciplines, the lack of documentation is attributed to the lack of training, the lack of time or missing rewards. This article addresses the hypothesis that scientists do document but do not know exactly what they need to document, why, and for whom. In order to evaluate the actual documentation practice of research software, we examined existing recommendations, and we evaluated their implementation in everyday practice using a concrete example from the engineering sciences and compared the findings with best practice examples. To get a broad overview of what documentation of research software entailed, we defined categories and used them to conduct the research. Our results show that the big picture of what documentation of research software means is missing. Recommendations do not consider the important role of researchers, who write research software, whose documentation takes mainly place in their research articles. Moreover, we show that research software always has a history that influences the documentation.

Introduction

Documentation of research software 1 in engineering science is inadequate 2 . Nevertheless, researchers–particularly within the FAIR (Findable, Accessible, Interoperable, Reusable) movement–state that documentation of research software as a major prerequisite for reuse 3 . Although, research data and software play a central role in the Cluster of Excellence “Data-Integrated Simulation Science (SimTech)” 4 , documentation is also lacking here.

But why is research software documented poorly? And what does good documentation actually imply? Previous approaches provide rather explanatory models why documentation is not done; they explain the missing documentation with lack of time 5 or insufficient training 6 . But is this really the case? Is it even clearly defined what documentation entails? Until now, incentives and rewards are missing for well documented research software. But, the scientific environment is changing, Gil et al. 7 observe a shift in the scientific environment in different areas: scientific publishing, scientists, public interest and funding. In recent years, these developments are gaining momentum with initiatives like EOSC (European Open Science Cloud) 8 and NFDI (National Research Data Infrastructure, Germany) 9 . Moreover, research funding agencies demand reusability; the guidelines for good scientific practices, for example, require documentation of research software explicitly 10 . Surprisingly, it remains rather unclear what good documentation of research software involves. We illustrate that there are recommendations on how to document (research) software. But are the recommendations actually applied?

The hypothesis of this paper is, that it is still unclear what good documentation actually involves. The approach intends to examine how documentation takes place in everyday work in a research environment in engineering science within the Cluster of Excellence, SimTech. We also examine if and how given recommendations are implemented. We defined categories to represent different documentation purposes. Based on these categories, we examined three different aspects:

  • Given recommendations on how research software should be documented.
  • An actual documentation workflow of a specific research software project from engineering science within SimTech.
  • Given documentation of two best practice examples within SimTech.

Previous approaches have been concerned with reasons why research software is poorly documented, but not with what good documentation actually entails. Also, it has not been investigated what and how documentation must be implemented in order to be perceived as good. It’s the intention of this approach to show what is missing and give an overview on who has to document for whom what, where, when, and how.

We want to investigate how research software is documented in a field where scientists usually don’t have a computer science background. Due to the highly disciplinary nature of research software, we focused on our discipline, Engineering Science. We conducted a multi-case study with a case-based approach 11 . To see how the documentation is implemented, one specific research software was chosen: Neweul-M 2 12 , a research software that has been developed over years in an institute by engineers without formal software development training. Neweul-M 2 continues to be actively developed and is often used to address specific research questions. We cross-case synthesis with two other research software’s documentation habits, to compare the gained insights. We selected these best practice examples because they received funding from the DFG (German Research Foundation) sustainable software funding call to improve their documentation 13 . In contrast to Neweul-M 2 , both best practice examples are open source. DuMu x 14 is a research software from engineering sciences, which is also programmed by Research Software Developers with an engineering background. The other example preCICE 15 is a research software developed from more experienced Research Software Developers working in an informatics institute; their users are mainly engineers. The central rival hypotheses we considered are the lack of time to document and the lack of training of researchers in software engineering 2 , 6 .

Two main research questions structure the investigation.

Research questions

  • What are the recommendations for documenting research software? Which rules and best practices exist? Do the given recommendations cover the defined categories?
  • What is the practice of documenting research software? How is research software documented in the daily life of researchers? Which workflows are implemented? What are the obstacles to document research software?

Data collection

For collecting data, we choose different sources of evidence:

  • Documentation : An evaluation of literature was conducted to assess what recommendations are given (RQ1). Furthermore, the three research software documentation were evaluated (RQ2).
  • Participant observation : Both authors are familiar with Neweul-M 2 , one author from a new Research Software Developer perspective, and the other from years of experience. One author is part of the project from the sustainable software funding call and has thus witnessed the discussions about the possibilities for improvement and shortcomings of the documentation of DuMu x (RQ2).
  • Direct observations : The concepts, thoughts, and insights were further discussed with the old and later the new Research Software Engineer from Neweul-M 2 and with DuMu x and preCICE Researcher Software Engineers (RQ2).
  • Interviews : The two best practice examples were evaluated with semi-structured interviews (RQ1, RQ2).

Data analysis

Our first idea was to evaluate the research software using given recommendations from the literature. As we soon noticed, the recommendations for research software do not give a complete picture of what documentation should actually contain. Therefore, we switched to an inductive strategy and formed categories that we consider necessary from everyday work with research software, supplemented with categories from literature and internet resources like blogs and wikis. Moreover, we decided to include the best practice examples to answer the research questions. We defined four documentation categories for research software, intending to picture possible documentation forms. Based on the defined categories, we evaluated the recommendations given for, Neweul-M 2 , DuMu x , and preCICE. In the following, we introduce the categories, followed by the recommendations and conclude with the analyzed research software examples.

Domain Research software can belong to different domains 16 : private , shared and open . Usually, research software is developed in the private domain with one main Research Software Developer. The shared domain varies from a few users at an institute to many users all over the world, nevertheless the research software is unavailable to the broader public. Published research software in the open domain is accessible for everyone. Where open can have two different meanings: only the source code is available open source or the software is developed openly. The domains may change over time and require more documentation, as more people need to understand the research software.

Role As we noticed, it is essential who documents for whom; we differentiate between three roles: Research Software Engineer (RSE) , Research Software Developer (RSD) and user . One person can have multiple roles, multiple people can share the role and the role of a person can change. As the roles in classical software engineering are conceptualized 17 , we defined the roles from our perspective—which is biased from our education as engineers and work in an interdisciplinary research cluster. When we speak about engineers, we think of the classic engineering fields such as mechanical engineering, civil engineering or chemical engineering. We explicitly neglect software engineers—due to their formal education in software development and maintenance, which is mostly missing in the other fields.

* Research Software Engineers are responsible (i) for the infrastructure and maintenance of the software, (ii) they give the rules of how research software should be written, (iii) but are often not part of the active feature development. The problems of funding, education and missing credit of Research Software Engineers are discussed in the RSE movement 18 .

* Users are (i) research software users who want to do either computer-aided engineering or computer-based experiments without writing code.

* Research Software Developers are (i) the link between Research Software Engineers and users , (ii) they develop new features, mainly to answer–with the research software–specific new research questions (iii) in engineering without education in software development and are often less experienced than Research Software Engineers. They typically need a specific answer for their research question, for which they need to implement a specific new or missing feature in existing research software. A typical example in Neweul-M2: A RSD implemented the calculation of reaction forces. This new feature can be reused for other research questions from other researchers and, therefore, need to be documented. RSDs are an essential part of the documentation process; they mainly know their developed features but are usually not deeply involved in the maintenance and documentation process.

Purpose The purposes describe the content of the documentation: why , what and how . The documentation of the problem should describe why the research software or a feature is written–similar to describing the research question, i.e. the RSE Manuscript/Dev docs row from Table ​ Table3. 3 . The feature’s documentation should describe what is needed to be done to solve the research question. How the feature is implemented should be documented in a technical documentation, i.e. the Help/Handbook/User Docs row from Table ​ Table3 3 .

Purpose of the different documentations.

P—Problem, F—Feature, I—Implementation.

Type The type describes the characteristics of the documentation 19 : problem , product and technology . The three above introduced categories can be expressed in different types of documentation: The documentation of the problem can involve how the problem is implemented and why a solution was preferred. The product documentation contains the list of all features provided by the software and how they work together. The technical documentation should help the RSD and RSE to understand the code, how the research software is engineered and how to build over the existing source code. It should contain different schemas about the used model, the logical, and physical architecture. The types are intended to be umbrella terms for different forms of documentation types. For example, code comments are a form of technical documentation or tutorials as a type of product description.

We assume that each of these categories requires a different type of documentation. In each domain, researchers can document purposes in their role as RSE or RSD for different roles. The combination leads to several types of content, which then appear in a variety of forms. For example, a RSD can describe why they solved what and how in a problem description such as an article. Or a RSE describes how to solve a problem for the user in a product description as a how-to-guide.

Recommendations

Aspects of good research software, and its documentation, has also been addressed in various recommendations. In order to find recommendations for documenting (research) software, we conducted a literature review in Web of Science using the terms “research software” and “documentation” or “reusability”. Most articles refer to the whole process of developing research software, and not only to documentation. Often just one small paragraph is dedicated to documentation. The selection of the articles was limited to those that include rules or best practices for documenting research software in at least one paragraph. Ten articles with interdisciplinary and different disciplinary focus were found. As described above, the evaluation of the recommendations did not provide a complete picture of what the documentation in our opinion should contain. Therefore, we also analysed the recommendations according to the categories we defined (Fig.  1 ).

An external file that holds a picture, illustration, etc.
Object name is 41598_2022_10376_Fig1_HTML.jpg

Different aspects of documentation.

Analysis of research software

Neweul-M 2 Neweul-M 2 is a software package that allows the dynamic analysis of mechanical systems in calculating multibody systems with symbolical equations 20 . The first version of Neweul was written in FORTRAN with an own symbolic formula manipulator engine in the mid 1970s and was rewritten in 2003 using MATLAB. The new version is called Neweul-M 2 . In Kurz et al. 12 , the history and changes are documented until the year 2010 (for further information see Table ​ Table1). 1 ). Neweul-M 2 is used from:

  • external people (user)
  • PhD students (RSD and user)
  • students (user)

Information about examined research software projects.

The source code is developed and administrated by PhD students within the developing institute, they aim for a degree in mechanical engineering and usually don’t have a formal software development education. One experienced RSD is the RSE, a new colleague is briefed as RSE from the previous one.

For the external people and students, a content-obscure (P-code) version of Neweul-M 2 is provided. One part of the documentation is in an integrated help within MATLAB. The help includes a product description, tutorials and examples and a function reference, automatically generated from the code. For PhD students from the developing institute, the full source code is accessible. The source code is managed via a Git repository hosted at an institutional GitLab instance. Bug fixes and support are the responsibility of the RSE. Another part of the documentation is done in a local wiki with information on how to get started and how to document with coding guidelines, tests and checklists. Decisions and discussions are documented via GitLab. For the RSE, an additional document gives information on how everything is organized. PhD students, who use Neweul-M 2 for their research, develop new features in Neweul-M 2 that they need for their research. They document these features mainly in publications.

DuMu x The research code for the free and open-source simulator is written in C++ and is based on DUNE (Distributed and Unified Numerics Environment). DuMu x stands for “DUNE for Multi-{Phase, Component, Scale, Physics, ...} flow and transport in porous media 21 . The main intention is to provide a sustainable and consistent framework for implementing and applying of porous media model concepts and constitutive relations (for further information see Table ​ Table1). 1 ). All documentation is linked on the Website. The documentation consists of a collection of documented code examples within the institute’s publicly accessible GitLab instance, a manual in PDF format, code documentation within Doxygen, a reference to the most important publications and a wiki that is still under construction. The software is written by PhD candidates in civil engineering with a predominantly engineering background, who have taught themselves to program.

preCICE The research software preCICE 22 is an open-source coupling library for partitioned multi-physics simulations, including fluid-structure interaction and conjugate heat transfer simulations. The research is about methods how two systems can be coupled (for further information see Table ​ Table1). 1 ). In preCICE the research question is not solved with the software, rather the research results are provided to users of the software. For this reason, there are only RSEs and users. The software is written by PhD candidates with different backgrounds, who are aiming for a degree in computer science. The documentation is bundled in a website. By using GitHub pages, pull requests can be made to all the documentation. The website is divided in quick start, docs, tutorials, community and blog. The section docs start with a user documentation with fundamentals, installation, configuration, tooling and provided adapters. The API is described in the category “couple your code”. Followed by a developer documentation, with a link to the source code documentation in Doxygen, and a description of coding conventions, tooling, workflow and testing. Even a description, how the documentation is build, exists. For the users–in addition to the conventional documentation–a community page gives insights on workshops, other contributors and publications. Furthermore, there is a blog where there is also the possibility to ask questions.

Validity analysis

We have deliberately chosen projects in which we can gain a more in-depth insight. These projects are in the engineering field to establish comparability of the training background of RSEs, RSDs and users. The interview partners are based on personal relationships and recommendations, which could lead to a specific research bias due to the small sample size and the personal connection. More extensive studies based on the research hypothesis of this study should be conducted in the future, e.g. at research software conferences. In order to validate our conclusions, we presented and discussed our results and methods with the RSEs and RSDs of the three software projects. We also presented a poster at the internal SimTech conference to receive feedback on our method and conclusions from other researchers. The feedback received confirmed our approach. The poster and other material is published in the case study database 23 . The selection of the case studies initially limits the generalizability of the results. However, the feedback received confirmed that our approach could be transferable to other research software projects. For example, PhD students at the conference confirmed that our approach is similar to their experiences with research software. The generalizability of the findings obtained in this study will be tested in another larger interview study with more extensive surveys in the future.

We present three main observations from the recommendations and the documentation of three research software examples, based on the categories that are presented in the method section.

Observation 1: A big picture is missing

A big picture is missing on what documentation of research software should contain and how it should be done. The examined recommendations focus only on specific aspects of research software documentation (see Fig.  1 ).

Observation 1.1: Problem and decision are undocumented

The recommendations rarely mention that the why should be documented and seldom take the underlying problem into account (see Table ​ Table2). 2 ). They refer–according to our categories–mainly to the technology of the research software. Their focus is on techniques (like version control systems and programs that generate a documentation out of comments in the code) not on content. Lee 6 state for example to “use automated documentation tools” and that “the best type of documentation is documentation that writes itself”, but do not explain what have to be the content of the automated documentation. Looking into the practice, all three examples use these automated documentation tools.

Purpose mentioned in the recommendations.

In Neweul-M 2 (see Table ​ Table3) 3 ) the function reference within the help is created with a given template, including: short description, syntax, long description, parameters, examples and references. In DuMu x (see Table ​ Table3) 3 ) the modules are documented with Doxygen 24 . In comparison to Neweul-M 2 the description involves the underlying concept, mostly explaining the formula behind the code. In preCICE (see Table ​ Table3) 3 ) as well, Doxygen is used with a generic documentation template: the parameters and a one line description is needed and an optional elaborate description. Here, the description do not contain the underlying concept. These tools are intended to document the code not the decisions and problems: RSDs document the problem and decision in research articles or thesis, which are not linked to the documentation; they implement new features to solve a specific task for a thesis; and they describe the problem only in the thesis referring to a specific version of the software. Eventually, the description of the problem and the feature differ from the software solution. Once the feature is included in the main branch, the dependencies are further maintained.

Observation 1.2: Shared and private domain are neglected

The recommendations focus on the open domain (see Table ​ Table4). 4 ). Especially, the documentation for the shared domain is rarely mentioned. Neweul-M 2 is a research software from the shared domain, the different documentation types live in different domains (see Table ​ Table5). 5 ). RSDs document mainly for their successors at the own institute. But the knowledge is not only transported by documentation: students of the institute learn about the software in their lectures and later on from their supervisor and fellow students or colleagues. In the best practice examples, the documentation is openly available.

Domains mentioned in the recommendations.

Domains of the different documentations.

P—Private, S—Shared, O—Open.

Observation 2: Research software has a history

In engineering science, PhD candidates usually stay round about six years, become experts in a very specific field and then leave. Successors–interested in the same topic–often do not have the chance to talk to them. So the experts omit feedback on their documentation and are ignorant of which questions they have to address in their documentation.

Figure ​ Figure2 2 describes the observed effect in Neweul-M 2 , showing the quality of the research software documentation over the different phases of research software development. The quality of the documentation behaves similarly to Kondratiev waves 31 : prosperity, recession, depression, and improvement. In the case of Neweul-M 2 one researcher developed the research software to solve a specific problem in the initiation phase. In the maturation phase, other researchers adopt the research software and more people get involved in the project. At the beginning, the documentation was good (enough) for the people who use the software (prosperity). Eventually, the initial RSD left, and new researchers added new features and modified the code. The quality of the documentation decreased (recession) in the saturation phase because modifications were not documented (depression); until a point was reached where the research software needed a refactoring. A new documentation is needed, usually written with a new tool (improvement). But the old documentation is still used because some aspects are important in there: different documentations exist for different roles in different places with different up-to-dateness. The descriptions of the implemented features in the articles referring to the research software before the refactoring are now more difficult or even impossible to reproduce. A new researcher inherits this history. Comparing this conceptual model with the other research software projects confirms the principle progression; the cycles are more or less pronounced depending on the dynamics of the research software and happen more or less rapidly. New RSEs do not necessarily contribute to the documentation quality. The funding received made it possible to solve many problems in the documentation, which were mainly pointed out by external RSDs and users. They both best practice examples benefit of being open source, receive more feedback from users outside the institute, and spend more effort and money to improve the documentation. So the effect of unconscious knowledge can be minimized.

An external file that holds a picture, illustration, etc.
Object name is 41598_2022_10376_Fig2_HTML.jpg

Quality of research software documentation over time. The research software undergoes different phases, from first implementation to continuous application. During these phases, the quality of the documentation varies accordingly. In particular, the change of RSE involves risks, but can also lead to improvements.

Observation 2.1: Unconscious knowledge

In Neweul-M 2 new users and RSDs are inducted to the software with the help of an more experienced RSD or the RSE. The knowledge of experienced RSDs is often unconscious, that means that they are not aware of their own knowledge and therefore do not explain important steps to the new RSD 32 . The effect shows up for example in the description of the workflow. It is described in the help theoretically but not concretely how and where information is stored and called. Relevant information about what is written in which files are presupposed. Usually, the RSE or experienced RSDs compensates this divergence. For example, where and how storing files is explained in a lecture about Neweul-M 2 , but this information is totally missing in the documentation. In the best practice examples the problem is less pronounced, because users from outside ask questions and draw attention to the problem, and especially in preCICE there is a workflow to update the help, according to the asked questions. Both projects have improved user-friendliness of the documentation through third-party funding. The recommendations do not address this problem.

Observation 2.2: Missing consistency

In Neweul-M 2 the documentation lives in different places: An integrated MATLAB help, mainly intended for users; an internal Wiki with more information, mainly intended for RSDs; and an internal document for the RSE with storage locations, workflows and pieces of the history. Not all the documentation is updated with changes in the code. RSDs usually archive their documentation with their thesis in a zip-file. This kind of documentation often refers to an obsolete version, inherited from the history. Moreover, outdated dependencies, which are not documented, invalidate the function or a lot of effort must be spent to fix the dependencies. Looking at the best practice examples: one of the first issues was to have all in one place. Through feedback from external users, the best practice examples are more consistent. Moreover, they spend money and effort to meet these challenges. In DuMu x all the documentation is linked on the homepage, an overview where to find which information is missing. In preCICE the documentation is directly on the homepage, with an overview where to find what. Additionally, there is even meta information about the documentation itself. The recommendations give hints about documentation tools, which can be used–how to structure this information is mentioned in 30 .

Observation 3: Research software has different purposes

Researchers write research software for different purposes. Therefore, the focus of the documentation can differ as well. The purpose of Neweul-M 2 is to implement a physical model to evaluate the same effects that occur in or beyond experiments. Engineers use already developed algorithms to solve their research question using research software. Here, in addition to documentation for the users, documentation for the RSDs is also necessary, because the scientists at the institute need to understand the results of their predecessors and want to be able to adapt them to their own needs.

The purpose of DuMu x is similar. However, there is a larger community outside the own institute, which uses the software and develops it accordingly.

The purpose of preCICE is to implement new algorithms and to show that these algorithms work. In preCICE the role of RSDs is not specifically taken into account. Users do couple their software with the help of preCICE but do not contribute to the code with features. So the documentation is mainly intended and improved for scientific users (see Table ​ Table6 6 ).

Authors and audience of the different documentations.

RSE—Research Software Engineer, RSD—Research Software Developer.

Observation 3.1: Research Software Developers are neglected

RSDs are often neglected as authors and as audience. As authors of the documentation, the recommendations consider mainly RSEs; the audience are RSEs and users (see Table ​ Table7). 7 ). The documentation requirements for RSDs are unclear. While in practice some requirements are given, the documentation reality often differs. In Neweul-M 2 the RSE has formalized the documentation of and for the RSDs through a given template. RSDs document directly in the code, which is automatically transferred to the help. The description often remains very short and are sometimes insufficient to be understood by others. No feedback from the successors is given about the quality of the documentation, because the Research Software Developers leave the institute and no longer notice possible problems (see Table ​ Table6 6 ).

Authors and audience of documentation mentioned in the recommendations.

In DuMu x RSDs have as well a guideline how and what they have to document. Experience shows that instead of following the guidelines, RSDs tend to keep the effort as small as possible and do not describe as expected, especially if the requirement is considered unnecessary (see Table ​ Table6 6 ).

The results undoubtedly show that research software is documented. We found out that a literature review could not answer RQ1. One hypothesis why we were not able to answer RQ1 from a literature review is Observation 1: The big picture is missing. Who documents what for whom in which domain and for what purpose. The primary hypothesis was that researchers document their software, but that this is not perceived as sufficiently documented. The data collected should provide information about who documents how and why the documentation is not sufficient. The already described rival hypotheses of lack of time and training seemed to be insufficient due to the existing documentation and software knowledge. Our study shows that not necessarily the motivation or missing skills lead to the opinion that software is not documented; rather, research software is not documented as expected.

Often the main problem is that documentation is seen as an event and not a process. Observation 2 shows that the RSEs do not necessarily contribute to documentation quality. Possible reasons for this are different perceptions among the RSEs about what good documentation is, and that old documentation is not discarded. However, funding can improve documentation because they can transform the event character of documentation into a process. The path dependency described in the results as well as the missing consistency and missing framework can be mitigated by setting uniform standards . This will always be a balancing act between freedom of research and predefined framework. However, the movement in given structures allows a more efficient work. Also, writing and documenting are not in itself the actual research work, but only the framework in which the research takes place. Researchers have other goals in writing and documenting code than professional software developers. Software developers aim to achieve the objectives defined in the product requirements: Specifying these requirements can be seen as a part of the documentation. Research software, on the other hand, is a means to an end and is not documented in product requirements. Researchers aim to answer research questions with the help of software 33 . Consequently, one part of the documentation happens in research articles, doctoral, master and bachelor theses. Those can be seen as delayed product requirements . Nevertheless, this kind of documentation is focused on the research question and not on the research software. Moreover, research papers discuss scientific results based on research software; but the research software behind the results is quickly outdated and developed further. Above all, the precise implementation of physic into code in the research software is not specified 34 , but particularly this point is essential for reusing the research software. Besides, articles document research results, not software. Sometimes the material is also not accessible or difficult to find . Certainly the lack of time to document is critical, but at a later stage much more time needs to be invested to support the users 30 and to understand the research software as a RSD. Some papers argue with the lack of training of researchers in software engineering 2 , 6 . But even in professional software development, documentation is neglected. Ludewig and Lichter 35 see two reasons for this neglection: Firstly, documentation is not necessarily learned even in software developer training and secondly, although it is said that documentation is important, other aspects usually have priority. Websites like “write the docs” 36 and The blog “I’d Rather be Writing” 37 gives advice for technical writers how to document code. Some approaches can certainly be adopted, though not everything can be transferred one-to-one to research software. Initiatives like “Better Scientific Software” 38 and the “Software Sustainability Institute” 39 draw attention to the problem and provide assistance. Although these sites are certainly helpful, you need to know them. They give only possible assistance and are not in themselves a standard. Nevertheless, a generally applicable standardization of documenting research software is difficult to find. Existing standards from software engineering 40 are complex, in parts not relevant for research software and difficult to access. Even if a standardization will be helpful to share results openly, it needs a clear guideline to document results for oneself and in a group. Therefore, all three examined research software have some forms of standardized templates, testing strategies and checklists provided by the RSE. However, compliance must also be checked, which in turn costs time. Especially, in engineering science several points add to the described difficulties:

  • use of other funding possibilities
  • existence of confidentiality reasons
  • fear of sabotaging the business model
  • modification of existing software, which is unclear how to document

But working together with industry demands good documented results–independent from publishing the software. Moreover, other RSDs need the documentation in order to understand the work from their predecessors. In Neweul-M 2 RSDs contribute to code and documentation. They have to understand the code, and they have to develop new features, which have to be documented. This part of the documentation can not be written but be controlled by a RSE. RSDs depend on the documentation of their predecessors and the existing structure. This experience happens as well in DuMu x . It can also be discussed whether some problems described could be avoided by making the software open source. There are good reasons, such as confidentiality obligations and also often a business model, that make these steps undesirable. Nevertheless, from our point of view, some investigated methods can be transferred to the shared domain.

All in all, it can be said that it should be clear who documents what and where. Hence, adopting best practices and principles from technical documentation and professional software development can help to improve the documentation of research software. Nevertheless, the study shows that all three case studies struggle with similar problems in the documentation and in part also decided on similar solution strategies, making transferability to other research software projects conceivable. Future research should explore how principles from the best practices examples can be transferred into the shared domain. A possible standardization of content would certainly be helpful here, but this cannot be solved by the individual scientist. The national and international initiatives certainly contribute to improving the situation here. One limitation of the current research is that the findings are not evaluated with more examples. This obstacle can be overcome in evaluating more software documentations. It can be expected that other research software in engineering science has similar problems. Moreover, there is a personal bias when trying to solve the problem with a given documentation. The experience showed that it was totally clear for the Research Software Engineer of the help where they can find the information and how the documentation is structured. But for inexperienced users, it is not obvious, they have to ask the Research Software Engineer. The effort to write documentation should be taken into account. Will the benefit exceed the effort that must be used for documentation? This can be an area for future research. As long as people are there who can help, it is just inefficient but not impossible to solve the given task without a sufficient documentation. But in the current discussion about FAIR, research software documentation plays an important role. The pay-off for Research Software Developers is may be marginal at the moment, but the importance is increasing. Good documentation pays off in the long run.

We discovered that researchers are often not aware for whom and why they document. A big picture what documentation for research software means is missing. The new approach in this paper is to define for what purpose and what appearance the documentation is intended and who has to document what for whom depending on the domain. The paper shows that even in recommendations, the objective of the documentation of research software is unclear. Until now the focus lies on Research Software Engineers and user, the researcher who develops features to an existing research software is here brought into focus. While essentially only the open domain has been considered so far, a substantial part of research software does not take place publicly in the first place; here, too, documentation is needed in order to ensure sustainable research.

Acknowledgements

Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany’s Excellence Strategy - EXC 2075 - 390740016. We acknowledge the support by the Stuttgart Center for Simulation Science (SimTech). We also want to thank the Research Software Engineers of the three examined research software examples Bernd Flemisch, Georg Schneider and Benjamin Uekermann for their support and helpful inputs.

Author contributions

S.H. studied the research software documentation, developed the methodology, and wrote the article. J.F. contributed to the writing process through valuable discussion and feedback, as well as his own experience in documenting research software. All authors read and approved the final manuscript.

Open Access funding enabled and organized by Projekt DEAL.

Competing interests

The authors declare no competing interests.

Publisher's note

Springer Nature remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

api documentation Recently Published Documents

Total documents.

  • Latest Documents
  • Most Cited Documents
  • Contributed Authors
  • Related Sources
  • Related Keywords

Documentation Matters: Human-Centered AI System to Assist Data Science Code Documentation in Computational Notebooks

Computational notebooks allow data scientists to express their ideas through a combination of code and documentation. However, data scientists often pay attention only to the code, and neglect creating or updating their documentation during quick iterations. Inspired by human documentation practices learned from 80 highly-voted Kaggle notebooks, we design and implement Themisto, an automated documentation generation system to explore how human-centered AI systems can support human data scientists in the machine learning code documentation scenario. Themisto facilitates the creation of documentation via three approaches: a deep-learning-based approach to generate documentation for source code, a query-based approach to retrieve online API documentation for source code, and a user prompt approach to nudge users to write documentation. We evaluated Themisto in a within-subjects experiment with 24 data science practitioners, and found that automated documentation generation techniques reduced the time for writing documentation, reminded participants to document code they would have ignored, and improved participants’ satisfaction with their computational notebook.

An interview with Joanna Suau from Infobip on the design of application programming interface (API) documentation

Abstract About Joanna Suau Joanna studied English literature and culture at the University of Silesia in Poland, where she was born. She did a technical writing postgraduate degree in the picturesque city of Krakow and moved to the U.K. in 2012, to work for shipping solutions provider Pierbridge, where she mainly focused on user guides and walkthroughs of various types of shipping applications. Interested in what makes an app tick, Joanna started learning programming language (JavaScript) and explored CSS and HTML in more detail. This is when she discovered her passion for writing clean and appealing developer-oriented documentation, and moved to the start-up company Moltin, to become a part of the Developer Success team. Joanna has changed industry, and currently works in the field of telecommunication. She works for a messaging services provider, Infobip, contributing content to their robust API solutions.

Rap4DQ: Learning to recommend relevant API documentation for developer questions

A case study of publishing internal apis to external users.

External service integration and adherence to industry standards has become ever more important for collections data management platforms. External APIs (Application Programming Interfaces), allow for the development of bi-directional data flows critical to service integration. In contrast to service-oriented backend APIs, public APIs must have continually up-to-date, comprehensive documentation that covers common use cases, on-the-fly request validation, and meaningful error messages. OpenAPI (OpenAPI Initiative 2021), a machine-readable API documentation specification can help significantly with testing and maintenance, and libraries can be used to automate common maintenance tasks. Specify 7 is a biological collections data management platform developed by the Specify Collections Consortium (Specify Software Consortium 2021). This presentation summarizes the challenges and lessons learned with publishing the existing backend Specify 7 API to a public-facing external API. Each Specify 7 API is composed of 200 resources. A standard set of CRUD (Create, Read, Update, Delete) operations is provided for each resource for client interaction with a group of service-based endpoints for bulk operations such as file uploads, file-based data imports, and attachment manipulation. To support the migration, we developed a custom library to enhance request validation. Parameter validation is extended through a real-time comparison against the existing schema and data. The library is available to the community under a MIT license on GitHub (https://github.com/specify/open_api_tools/). In this presentation, we will close with an overview of the next steps for the Specify 7 public API. These include: An update to the latest OpenAPI specification, version 3.1. The latest version aims to increase compatibility with the Javascript Object Notation (JSON) Schema specification, and thus would allow us to use JSON Schema (IETF Trust 2021) validation frameworks. An in-depth evaluation of GraphQL for its ability to force all endpoints to be strongly typed and automatic validation of request parameters and response objects. An update to the latest OpenAPI specification, version 3.1. The latest version aims to increase compatibility with the Javascript Object Notation (JSON) Schema specification, and thus would allow us to use JSON Schema (IETF Trust 2021) validation frameworks. An in-depth evaluation of GraphQL for its ability to force all endpoints to be strongly typed and automatic validation of request parameters and response objects.

Applying Model-Driven Engineering to Stimulate the Adoption of DevOps Processes in Small and Medium-Sized Development Organizations

AbstractMicroservice architecture (MSA) denotes an increasingly popular architectural style in which business capabilities are wrapped into autonomously developable and deployable software components called microservices. Microservice applications are developed by multiple DevOps teams each owning one or more services. In this article, we explore the state of how DevOps teams in small and medium-sized organizations (SMOs) cope with MSA and how they can be supported. We show through a secondary analysis of an exploratory interview study comprising six cases, that the organizational and technological complexity resulting from MSA poses particular challenges for small and medium-sized organizations (SMOs). We apply model-driven engineering to address these challenges. As results of the second analysis, we identify the challenge areas of building and maintaining a common architectural understanding, and dealing with deployment technologies. To support DevOps teams of SMOs in coping with these challenges, we present a model-driven workflow based on LEMMA—the Language Ecosystem for Modeling Microservice Architecture. To implement the workflow, we extend LEMMA with the functionality to (i) generate models from API documentation; (ii) reference remote models owned by other teams; (iii) generate deployment specifications; and (iv) generate a visual representation of the overall architecture. We validate the model-driven workflow and our extensions to LEMMA through a case study showing that the added functionality to LEMMA can bring efficiency gains for DevOps teams. To develop best practices for applying our workflow to maximize efficiency in SMOs, we plan to conduct more empirical research in the field in the future.

Graph-Augmented Code Summarization in Computational Notebooks

Computational notebooks allow data scientists to express their ideas through a combination of code and documentation. However, data scientists often pay attention only to the code and neglect the creation of the documentation in a notebook. In this work, we present a human-centered automation system, Themisto, that can support users to easily create documentation via three approaches: 1) We have developed and reported a GNN-augmented code documentation generation algorithm in a previous paper, which can generate documentation for a given source code; 2) Themisto also implements a query-based approach to retrieve the online API documentation as the summary for certain types of source code; 3) Lastly, Themistoalso enables a user prompt approach to motivate users to write documentation for some use cases that automation does not work well.

Scout-bot: Leveraging API Community Knowledge for Exploration and Discovery of API Learning Resources

Application Programming Interface (API) is a core technology that facilitates developers’ productivity by enabling the reuse of software components. Understanding APIs and gaining knowledge about their usage are therefore fundamental needs for developers. Here, API documentation plays a pivotal role in enabling developers to take full advantage of the benefits brought by APIs. The quality of API documentation has therefore become an important concern given the celerity and dynamics at which APIs are now being made available to users. This article aims at exploring existing research in the area of API documentation in order to identify the associated quality dimensions addressed by the literature. The research is carried out as a systematic mapping study where 103 research papers selected from the literature were reviewed and a total of 5 core quality dimensions were identified and analyzed. By focusing on the two most relevant quality dimensions (understandability and completeness), this article presents an approach to enable API users to explore, discover and learn about APIs through API topic issues discussed in Stack Overflow (SO). We demonstrate the feasibility of our approach through Scout-bot, our tool for exploration and discovery of API topic issues.

QA4GIS: A novel approach learning to answer GIS developer questions with API documentation

Automatic api usage scenario documentation from technical q&a sites.

The online technical Q&A site Stack Overflow (SO) is popular among developers to support their coding and diverse development needs. To address shortcomings in API official documentation resources, several research works have thus focused on augmenting official API documentation with insights (e.g., code examples) from SO. The techniques propose to add code examples/insights about APIs into its official documentation. Recently, surveys of software developers find that developers in SO consider the combination of code examples and reviews about APIs as a form of API documentation, and that they consider such a combination to be more useful than official API documentation when the official resources can be incomplete, ambiguous, incorrect, and outdated. Reviews are opinionated sentences with positive/negative sentiments. However, we are aware of no previous research that attempts to automatically produce API documentation from SO by considering both API code examples and reviews. In this article, we present two novel algorithms that can be used to automatically produce API documentation from SO by combining code examples and reviews towards those examples. The first algorithm is called statistical documentation, which shows the distribution of positivity and negativity around the code examples of an API using different metrics (e.g., star ratings). The second algorithm is called concept-based documentation, which clusters similar and conceptually relevant usage scenarios. An API usage scenario contains a code example, a textual description of the underlying task addressed by the code example, and the reviews (i.e., opinions with positive and negative sentiments) from other developers towards the code example. We deployed the algorithms in Opiner, a web-based platform to aggregate information about APIs from online forums. We evaluated the algorithms by mining all Java JSON-based posts in SO and by conducting three user studies based on produced documentation from the posts. The first study is a survey, where we asked the participants to compare our proposed algorithms against a Javadoc-syle documentation format (called as Type-based documentation in Opiner). The participants were asked to compare along four development scenarios (e.g., selection, documentation). The participants preferred our proposed two algorithms over type-based documentation. In our second user study, we asked the participants to complete four coding tasks using Opiner and the API official and informal documentation resources. The participants were more effective and accurate while using Opiner. In a subsequent survey, more than 80% of participants asked the Opiner documentation platform to be integrated into the formal API documentation to complement and improve the API official documentation.

Automatic Detection of Five API Documentation Smells: Practitioners’ Perspectives

Export citation format, share document.

  • Alzheimer's disease & dementia
  • Arthritis & Rheumatism
  • Attention deficit disorders
  • Autism spectrum disorders
  • Biomedical technology
  • Diseases, Conditions, Syndromes
  • Endocrinology & Metabolism
  • Gastroenterology
  • Gerontology & Geriatrics
  • Health informatics
  • Inflammatory disorders
  • Medical economics
  • Medical research
  • Medications
  • Neuroscience
  • Obstetrics & gynaecology
  • Oncology & Cancer
  • Ophthalmology
  • Overweight & Obesity
  • Parkinson's & Movement disorders
  • Psychology & Psychiatry
  • Radiology & Imaging
  • Sleep disorders
  • Sports medicine & Kinesiology
  • Vaccination
  • Breast cancer
  • Cardiovascular disease
  • Chronic obstructive pulmonary disease
  • Colon cancer
  • Coronary artery disease
  • Heart attack
  • Heart disease
  • High blood pressure
  • Kidney disease
  • Lung cancer
  • Multiple sclerosis
  • Myocardial infarction
  • Ovarian cancer
  • Post traumatic stress disorder
  • Rheumatoid arthritis
  • Schizophrenia
  • Skin cancer
  • Type 2 diabetes
  • Full List »

share this!

May 21, 2024

This article has been reviewed according to Science X's editorial process and policies . Editors have highlighted the following attributes while ensuring the content's credibility:

fact-checked

reputable news agency

Cyberattack forces Michigan hospitals to switch to paper documentation, divert some patients elsewhere

by Hannah Mackay, The Detroit News

hospital

A cyberattack against Michigan Ascension hospitals continues to cause issues, forcing it to divert some ambulances to other hospitals for certain medical issues, delay diagnostic imaging and affecting its ability to fill prescriptions.

A spokesperson for Ascension didn't respond to a request for comment about how the attack continues to impact its operations. But the system said in a statement May 15 that it had even switched to manual paperwork in the attack's aftermath.

Michigan Ascension hospitals, physician offices, and care sites remain open.

Ascension first detected unusual activity on select technology network systems on May 8. Access to systems and patient care across 15 states has been disrupted since then as the company investigates the ransomware attack.

While working to restore systems and determine what information, if any, has been affected, hospitals have transitioned to manual systems for patient documentation. Ascension said that may cause delays and longer-than-usual wait times at previously scheduled appointments and elective surgeries.

"To help with delays, patients should bring notes on symptoms and a list of current medications, including prescription numbers or bottles," an Ascension spokesperson said in the May 15 statement.

All Ascension emergency rooms in Michigan are still open and accepting walk-ins, and ambulatory diversion is a "normal course of operation, a fluid practice, and is dependent on a number of factors, including case severity, service lines, and availability," according to the statement. Ascension's emergency rooms are in constant communication with emergency medical service providers to ensure cases are triaged more effectively, a spokesperson said last week.

If any rescheduling is needed for surgical, diagnostic, or other doctor's appointments patients will be contacted directly, Ascension said Wednesday.

Ascension did not immediately respond to a request for comment Monday on which Michigan facilities are diverting ambulatory cases and or temporarily delaying diagnostic imaging and testing.

The health care system has notified law enforcement and government agencies including the Federal Bureau of Investigations, Cybersecurity and Infrastructure Security Agency, Department of Health and Human Services, and American Hospital Association about the ransomware attack.

"Despite the challenges posed by the recent ransomware incident, patient safety continues to be our utmost priority," an Ascension spokesperson said last week. "Our dedicated doctors, nurses, and care teams are demonstrating incredible thoughtfulness and resilience as we utilize manual and paper based systems during the ongoing disruption to normal systems."

Ascension is also working with forensic experts from three cybersecurity firms, Mandiant, CYPFER, and Palo Alto Networks Unit 42, to investigate the attack and restore systems, they said in a system-wide update.

2024 The Detroit News. Distributed by Tribune Content Agency, LLC.

Explore further

Feedback to editors

documentation of research paper

Study: Newborns whose mother spoke in a mix of languages during pregnancy are more sensitive to a range of sound pitches

4 hours ago

documentation of research paper

Study finds ultraviolet radiation may affect subcutaneous fat regulation, could lead to new obesity treatments

documentation of research paper

Regular fish oil supplement use might increase first-time heart disease and stroke risk

9 hours ago

documentation of research paper

Pedestrians may be twice as likely to be hit by electric/hybrid cars as petrol/diesel ones

documentation of research paper

Study finds jaboticaba peel reduces inflammation and controls blood sugar in people with metabolic syndrome

11 hours ago

documentation of research paper

Study reveals how extremely rare immune cells predict how well treatments work for recurrent hives

12 hours ago

documentation of research paper

Researchers find connection between PFAS exposure in men and the health of their offspring

documentation of research paper

Researchers develop new tool for better classification of inherited disease-causing variants

documentation of research paper

Specialized weight navigation program shows higher use of evidence-based treatments, more weight lost than usual care

documentation of research paper

Exercise bouts could improve efficacy of cancer drug

13 hours ago

Related Stories

documentation of research paper

Cyberattack cripples major US health care network

May 10, 2024

documentation of research paper

Major Florida hospital hit by possible ransomware attack

Feb 3, 2023

documentation of research paper

A large US health care tech company was hacked. It's leading to billing delays and security concerns

Mar 1, 2024

documentation of research paper

Google healthcare project targeted by Congress committee

Nov 19, 2019

documentation of research paper

Ransomware attack prompts multistate hospital chain to divert some emergency room patients elsewhere

Nov 28, 2023

documentation of research paper

Ransomware attack on China's biggest bank disrupts Treasury market trades

Nov 10, 2023

Recommended for you

documentation of research paper

Taking a leave of absence can harm medical students' match prospects, finds study

Apr 16, 2024

documentation of research paper

In the nation's M.D.-Ph.D. programs, the socioeconomic gap widens

Mar 12, 2024

documentation of research paper

Police transport may influence restraint use in the emergency department

Feb 22, 2024

documentation of research paper

New tool can assess the climate of equity and inclusion in medical schools

Feb 21, 2024

documentation of research paper

Study: Why nurses are too often missing in health care leadership with major barriers to career advancement

Dec 13, 2023

documentation of research paper

The top Medical Xpress articles of 2023

Dec 12, 2023

Let us know if there is a problem with our content

Use this form if you have come across a typo, inaccuracy or would like to send an edit request for the content on this page. For general inquiries, please use our contact form . For general feedback, use the public comments section below (please adhere to guidelines ).

Please select the most appropriate category to facilitate processing of your request

Thank you for taking time to provide your feedback to the editors.

Your feedback is important to us. However, we do not guarantee individual replies due to the high volume of messages.

E-mail the story

Your email address is used only to let the recipient know who sent the email. Neither your address nor the recipient's address will be used for any other purpose. The information you enter will appear in your e-mail message and is not retained by Medical Xpress in any form.

Newsletter sign up

Get weekly and/or daily updates delivered to your inbox. You can unsubscribe at any time and we'll never share your details to third parties.

More information Privacy policy

Donate and enjoy an ad-free experience

We keep our content available to everyone. Consider supporting Science X's mission by getting a premium account.

E-mail newsletter

documentation of research paper

The Documentary Depth of Hadith Transmission

  • Said Aljoumani

The transmission of hadith prompted substantial documentation and subsequent archiving. This article presents a recently rediscovered type of document belonging to this paper trail: audition attendance lists ( awrāq al-samā ʿ). Preceding the better-known audition certificate ( samāʿ ), an audition attendance list was sometimes used in the transmission of particularly long books in order to keep track of the attendance of sometimes hundreds of participants in audition sessions. Here we concentrate on one audition attendance list produced in the ninth/fifteenth century in Cairo for a transmission of the most famous hadith collection, the Ṣaḥīḥ al-Bukhārī . We introduce this kind of document, propose a reading of our particular sample, and discuss certain functions of audition attendance lists. We argue that these lists reveal a hitherto unknown depth in the documentary machinery of textual transmission.

Creative Commons License

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License .

Copyright (c) 2024 Said Aljoumani, Benedikt Reier

IMAGES

  1. Research Document Example

    documentation of research paper

  2. Research Paper And Report Outline4

    documentation of research paper

  3. 🌈 How to write a research paper example. How to Write a Research Paper

    documentation of research paper

  4. Research Paper Sample Pdf Chapter Download Scientific pertaining to

    documentation of research paper

  5. Sample Research Paper

    documentation of research paper

  6. Draft For Research Paper Example : How to Write an APA Research Paper

    documentation of research paper

VIDEO

  1. Final Year Projects

  2. How to Write Project Documentation using Chat Gpt

  3. Week 13: MLA Documentation

  4. Common Types of Research Papers for Publication

  5. What is a Research

  6. 230524 EARLY CHILDHOOD EDUCATION Topics for RESEARCH Methodology

COMMENTS

  1. 13.1 Formatting a Research Paper

    Set the top, bottom, and side margins of your paper at 1 inch. Use double-spaced text throughout your paper. Use a standard font, such as Times New Roman or Arial, in a legible size (10- to 12-point). Use continuous pagination throughout the paper, including the title page and the references section.

  2. Appendix B: A Guide to Research and Documentation

    22.1 Choosing a Documentation Format. As a rule, your assignments requiring research will specify a documentation format. If you are free to use the style of your choice, you can choose any format you want as long as you are consistent, but you should know that certain disciplines tend to use specific documentation styles:

  3. Library Guides: How to Write Good Documentation: Home

    An important tip: Naming files should be descriptive and consistent! Date format (ISO 8601 Standard): YYYYMMDDThhmmss. Make file names sortable and searchable: Project or experiment name. Researcher name/initials. Date or date range of collection version. An example for README file. An example of code documentation.

  4. About Documentation Styles

    A documentation style is a standard approach to the citation of sources that the author of a paper has consulted, abstracted, or quoted from. It prescribes methods for citing references within the text, providing a list of works cited at the end of the paper, and even formatting headings and margins. Different academic disciplines use different ...

  5. Documenting Sources

    Documenting Sources. Documenting means showing where you got source information that's not your own. Remember, a research paper blends your ideas with ideas and information from other sources. Documentation shows the reader what ideas are yours and what information and ideas you've taken from a source to support your point of view.

  6. Documentation in Research Papers

    Updated on November 04, 2019. In a report or research paper, documentation is the evidence provided for information and ideas borrowed from others. That evidence includes both primary sources and secondary sources . There are numerous documentation styles and formats, including MLA style (used for research in the humanities), APA style ...

  7. Research Paper Format

    Formatting an MLA paper. The main guidelines for writing an MLA style paper are as follows: Use an easily readable font like 12 pt Times New Roman. Set 1 inch page margins. Apply double line spacing. Indent every new paragraph ½ inch. Use title case capitalization for headings.

  8. PDF Managing Your Research Data and Documentation

    A renewed emphasis on teaching research documentation practices is necessary at this point because recent technological advances have made research documentation both more convenient and more complicated. Decades ago, everything researchers did was on paper, and document-ing research largely meant storing a lot of file boxes and folders. Clunky

  9. Types of Documentation

    The two most common types of documentation used in research are note citations and parenthetical citations (Winkler & McCuen-Metherell, 2008, p. 4). You might also see terms like "footnotes," "endnotes," or "references" when learning about documentation practices. Refer to the required style guide and your instructor when ...

  10. How to Write a Research Paper

    Create a research paper outline. Write a first draft of the research paper. Write the introduction. Write a compelling body of text. Write the conclusion. The second draft. The revision process. Research paper checklist. Free lecture slides.

  11. Free Research Paper Template (Word Doc & PDF)

    The research paper template covers the following core sections: The title page/cover page. Abstract (sometimes also called the executive summary) Section 1: Introduction. Section 2: Literature review. Section 3: Methodology. Section 4: Findings /results. Section 5: Discussion. Section 6: Conclusion.

  12. Writing a Research Paper Introduction

    Table of contents. Step 1: Introduce your topic. Step 2: Describe the background. Step 3: Establish your research problem. Step 4: Specify your objective (s) Step 5: Map out your paper. Research paper introduction examples. Frequently asked questions about the research paper introduction.

  13. PDF Formatting a Research Paper

    Text Formatting. Heading and Title. Running Head with Page Numbers. Placement of the List of Works Cited. Tables and Illustrations. Paper and Printing. Corrections and Insertions on Printouts. Binding a Printed Paper. Electronic Submission.

  14. Good documentation practice in clinical research

    Inadequacies in documentation could be the result of lack of training and experience in good understanding of clinical research and documentation requirements. ... verifying eligibility, use of right tools such as diaries, source document worksheets, OPD papers, copies of prescriptions, etc; ways to avoid multiple records and in case of ...

  15. Research Documentation

    Research documentation should include all the information that is needed to understand the underlying design for the research output. This can include descriptions of: ... If you are preparing documentation to accompany the publication of an academic output such as a working paper or journal article, the most common form of research ...

  16. Guides: Documenting Research Data: Code Documentation

    Best Practices for Code Documentation. General guidelines and best practices for documenting code: A Guide to Reproducible Code in Ecology and Evolution : A guide to write reproducible code for researchers in Ecology and Evolution fields, created by British Ecological Society . Most guidelines can still be applied to other disciplines.

  17. Ten simple rules for writing a paper about scientific software

    Rule 6: Make a clear distinction between code documentation and research results. Whenever software is intended for reuse, high-quality documentation is crucial. However, peer-reviewed papers are arguably not where documentation should be presented. ... There is a frustrating scenario that plays out often when performing computational research ...

  18. A Review of Documentation: A Cross-Disciplinary Perspective

    This paper aims to act as a cross-disciplinary reference for the analysis of documents. across different specialised disciplines. Given the rising quality, quantity, accessibility, and ...

  19. Documenting research software in engineering science

    Introduction. Documentation of research software 1 in engineering science is inadequate 2.Nevertheless, researchers-particularly within the FAIR (Findable, Accessible, Interoperable, Reusable) movement-state that documentation of research software as a major prerequisite for reuse 3.Although, research data and software play a central role in the Cluster of Excellence "Data-Integrated ...

  20. Research Paper Appendix

    Research Paper Appendix | Example & Templates. Published on August 4, 2022 by Tegan George and Kirsten Dingemanse. Revised on July 18, 2023. An appendix is a supplementary document that facilitates your reader's understanding of your research but is not essential to your core argument. Appendices are a useful tool for providing additional information or clarification in a research paper ...

  21. (PDF) Quality of Nursing Documentation: Paper‐Based ...

    Aim and objective: To assess and compare the quality of paper-based and electronic-based health records. The comparison examined three criteria: content, documentation process, and structure.

  22. api documentation Latest Research Papers

    The Creation . Api Documentation. Computational notebooks allow data scientists to express their ideas through a combination of code and documentation. However, data scientists often pay attention only to the code, and neglect creating or updating their documentation during quick iterations. Inspired by human documentation practices learned ...

  23. Cyberattack forces Michigan hospitals to switch to paper documentation

    Citation: Cyberattack forces Michigan hospitals to switch to paper documentation, divert some patients elsewhere (2024, May 21 ... A boost for HIV vaccine research: Studies present comprehensive ...

  24. The Documentary Depth of Hadith Transmission

    The transmission of hadith prompted substantial documentation and subsequent archiving. This article presents a recently rediscovered type of document belonging to this paper trail: audition attendance lists (awrāq al-samāʿ). Preceding the better-known audition certificate (samāʿ), an audition attendance list was sometimes used in the transmission of particularly long books in order to ...