This is some research code that is contained in a Python function.
This is some research code that is contained in an R function.
This is a function written in the R programming language that calculates a mathematical result, the details of which aren’t relevant. This code has plenty of documentation to help us read and understand it. @@ -652,7 +652,7 @@
Read and evaluate this code.
Content from Writing README files
Last updated on 2024-07-22 | +
Last updated on 2024-09-12 | Edit this page
Use the File
Manager to create a new directory called oddsong.
Inside that folder, create a new text file called
@@ -915,7 +915,7 @@
Use the Finder
file manager to create a new directory called oddsong.
Inside that folder, create a new text file called
@@ -938,35 +938,38 @@
The essentials contents of a README file are:
It can be useful to signpost to other, related useful software tools by providing links and explaining how other software is related or different to this project when it comes to addressing these kinds of research problems.
-Put yourself in the shoes of a researcher who has encountered your +
Put yourself in the position of a researcher who has encountered your software for the first time. Consider, if you had to start from square -one, how would you like the code to be introduced to you? Remember: -things that are obvious to you and your colleagues may not be clear to -others. What assumed knowledge must you explicitly explain to get them -up to speed?
+one, how would you like the code to be introduced to you? +Remember: things that are obvious to you and your colleagues may not +be clear to others. What assumed knowledge must you +explicitly explain to get them up to speed?
Consider a research code project you’ve worked on. Discuss the technical prerequisites for that software or system. What would someone @@ -1029,18 +1032,21 @@
The writing style should be concise, jargon-free, clear, and pitched -at the appropriate level to the intended target audience. All technical -terms and acronyms should be explained. However, don’t reinvent the -wheel by defining all the terms used, instead link to a reliable -external source or journal article.
+The writing style should be concise, jargon-free, consistent, and +pitched at the appropriate level to the intended target audience. All +technical terms and acronyms should be explained. However, don’t +reinvent the wheel by defining all the terms used, instead link to a +reliable external source or journal article.
+For more information about good writing style, please refer to these +style +guides.
Discuss with the group:
Not all READMEs must follow this structure. Always adapt the format +of your documentation to suit the specific needs of your audience.
Most people prefer to use a file format that allows you to create headers to organise the content into sections or chapters, which is much clearer for the reader.
-In this case, a Markdown document may be used. Markdown is a simple -mark-up language that allows you to format your text using symbols to -represent headers, bold text, bullet lists, etc. that are displayed to -the user in an appealing way. The Markdown syntax will be converted into -appealing visual styles that make your documentation more aesthetically -pleasing and easier to read.
+In this case, a Markdown +document may be used. Markdown is a simple markup language that +allows you to format your text using symbols to represent headers, bold +text, bullet lists, etc. that are displayed to the user in an appealing +way. The Markdown syntax will be converted into appealing visual styles +that make your documentation more aesthetically pleasing and easier to +read.
+A markup +language is a system of special characters that are used to +decorate or format pieces of plain text. The +syntax normally consists of symbols or tags that are used to +encode text, which means implying meaning to make it +more information-rich. It can be used to structure a documented into +sections to provide logical organisation so that it’s easier to +navigate.
+Typically, a markup language is edited in a similar way to a computer +programming language, and is rendered into a document +with various rich text formatting such as headers, bold face fonts, +etc.
+Use File
Explorer to rename
the file from README.txt to README.md.
README.md.Use the File
Manager to rename
the file from README.txt to README.md.
mv README.txt README.md
Use the Finder
to rename
the file from README.txt to README.md.
These may be used to add emphasis to parts of the text or highligh +key words and phrases. Using text formatting makes your software +documentation easier to skim-read, so researchers can quickly find the +part of the text that’s relevant for what they’re working on.
+Identify several key words in your README file. Highlight +them in using a bold font face.
+The Markdown syntax for bold font is to wrap the text in two
+asterixes **. This may be applied to single words or to
+phrases.
For example:
+ +Identify a bird based on the sound of its call.
+ +Identify a bird based on the sound of its +call.
+This will be rendered with the following apperearance:
@@ -1331,22 +1407,25 @@Code blockspi = 3.14 -
+++---Callout
++Markdown
You can learn more about writing documents using Markdown at Markdown Guide, a reference for using this syntax.
Remember, the README file is a first impression that research users -will receive for your software. Make them informative and user-friendly -to enhance the research experience for others and foster -collaboration.
+Remember, the README file is a first impression that +research users will receive for your software. A README contains a brief +description of the software, installation instructions, and a usage +guide. Make them informative and user-friendly to enhance the research +experience for others and foster collaboration. The writing style should +be concide, clear, and explain technical terms. Use diagrams and +screenshots for clarity.
@@ -1359,23 +1438,27 @@Key Points
users on installation, usage, and understanding its capabilities.Consider the user’s technical background; write clearly and avoid jargon. -A README contains a brief description of the software, installation -instructions, and a usage guide. -The writing style should be concide, clear, and explain technical -terms. -Use diagrams and screenshots for clarity. Markdown is a recommended format for creating headers, bold text, bullet points, etc. Further resources +
+
+For more information about writing basic software documentation, +please review the following materials:
++
-- Raphael Pierzina Hi, +my name is README! +
+
Content from Documentation strings
+ -->Content from Documentation strings
Last updated on 2024-09-12 | @@ -1455,7 +1538,7 @@
In R, we use a comment with a single quote #' to specify
a documentation string for a function.
oddsong.R;Let’s view the help text for an in-built function
abs() that finds the absolute value of a number.
These code examples can be used as automatic tests using the doctest module which is built into Python.
@@ -1748,7 +1831,7 @@There are several different standards for documentation strings. A standard is a convention that determines how @@ -3411,7 +3494,7 @@
On Windows operating systems, press the Windows key and type in “command”. The start menu will find the “Command Prompt” app. Press Enter or click on the Command Prompt icon to launch the @@ -3431,7 +3514,7 @@
On Ubuntu, press Ctrl + Alt + T to open a terminal.
You can also open Dash and search for “Terminal”. For detailed
instructions, please read Opening
@@ -3446,7 +3529,7 @@ BASH
bob@myUbuntuPC:~$
Please read Open or quit Terminal on Mac on the Terminal User Guide for macOS.
@@ -3480,7 +3563,7 @@On Windows, the dir command is used to list the contents of a directory. When you enter this command and press Enter
@@ -3510,7 +3593,7 @@To show the contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
location.
README.txtThe macOS terminal is very similar to the Linux one. To show the
contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
@@ -3560,7 +3643,7 @@
When using shell commands, we use the words option, flag, and arguments to describe @@ -3589,7 +3672,7 @@
In the Windows command line, we use the /? argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the dir
@@ -3624,7 +3707,7 @@
In the Linux command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -3653,7 +3736,7 @@
In the macOS command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -3705,7 +3788,7 @@
This is a mechanism that tells Python how we want users to interact with our software.
@@ -3750,7 +3833,7 @@When you run the python -m oddsong command, Python runs
the main module as a script.
When we run our script as before, it will run like normal with no change in behaviour.
@@ -3920,7 +4003,7 @@The code now looks something like that shown below.
We can achieve this in our example script by adding a
help string.
We define the description when creating our argument parser object.
diff --git a/cli.html b/cli.html index e875b05..6c32e54 100644 --- a/cli.html +++ b/cli.html @@ -384,7 +384,7 @@On Windows operating systems, press the Windows key and type in “command”. The start menu will find the “Command Prompt” app. Press Enter or click on the Command Prompt icon to launch the @@ -404,7 +404,7 @@
On Ubuntu, press Ctrl + Alt + T to open a terminal.
You can also open Dash and search for “Terminal”. For detailed
instructions, please read Opening
@@ -419,7 +419,7 @@ BASH
bob@myUbuntuPC:~$
Please read Open or quit Terminal on Mac on the Terminal User Guide for macOS.
@@ -452,7 +452,7 @@On Windows, the dir command is used to list the contents of a directory. When you enter this command and press Enter
@@ -482,7 +482,7 @@To show the contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
location.
README.txtThe macOS terminal is very similar to the Linux one. To show the
contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
@@ -531,7 +531,7 @@
When using shell commands, we use the words option, flag, and arguments to describe @@ -560,7 +560,7 @@
In the Windows command line, we use the /? argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the dir
@@ -595,7 +595,7 @@
In the Linux command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -624,7 +624,7 @@
In the macOS command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -673,7 +673,7 @@
This is a mechanism that tells Python how we want users to interact with our software.
@@ -718,7 +718,7 @@When you run the python -m oddsong command, Python runs
the main module as a script.
When we run our script as before, it will run like normal with no change in behaviour.
@@ -885,7 +885,7 @@The code now looks something like that shown below.
We can achieve this in our example script by adding a
help string.
We define the description when creating our argument parser object.
diff --git a/docstrings.html b/docstrings.html index 5d4ae61..c1ea031 100644 --- a/docstrings.html +++ b/docstrings.html @@ -360,7 +360,7 @@In R, we use a comment with a single quote #' to specify
a documentation string for a function.
oddsong.R;Let’s view the help text for an in-built function
abs() that finds the absolute value of a number.
These code examples can be used as automatic tests using the doctest module which is built into Python.
@@ -645,7 +645,7 @@There are several different standards for documentation strings. A standard is a convention that determines how diff --git a/index.html b/index.html index d757fa8..f39643a 100644 --- a/index.html +++ b/index.html @@ -385,7 +385,7 @@
This is some research code that is contained in a Python function.
This is some research code that is contained in an R function.
This is a function written in the R programming language that calculates a mathematical result, the details of which aren’t relevant. This code has plenty of documentation to help us read and understand it. @@ -655,7 +655,7 @@
Read and evaluate this code.
Content from Writing README files
Last updated on 2024-07-22 | +
Last updated on 2024-09-12 | Edit this page
Estimated time: 12 minutes
@@ -892,7 +892,7 @@Use the File
Manager to create a new directory called oddsong.
Inside that folder, create a new text file called
@@ -919,7 +919,7 @@
Use the Finder
file manager to create a new directory called oddsong.
Inside that folder, create a new text file called
@@ -942,35 +942,38 @@
The essentials contents of a README file are:
It can be useful to signpost to other, related useful software tools by providing links and explaining how other software is related or different to this project when it comes to addressing these kinds of research problems.
-Put yourself in the shoes of a researcher who has encountered your +
Put yourself in the position of a researcher who has encountered your software for the first time. Consider, if you had to start from square -one, how would you like the code to be introduced to you? Remember: -things that are obvious to you and your colleagues may not be clear to -others. What assumed knowledge must you explicitly explain to get them -up to speed?
+one, how would you like the code to be introduced to you? +Remember: things that are obvious to you and your colleagues may not +be clear to others. What assumed knowledge must you +explicitly explain to get them up to speed?
Consider a research code project you’ve worked on. Discuss the technical prerequisites for that software or system. What would someone @@ -1033,18 +1036,21 @@
The writing style should be concise, jargon-free, clear, and pitched -at the appropriate level to the intended target audience. All technical -terms and acronyms should be explained. However, don’t reinvent the -wheel by defining all the terms used, instead link to a reliable -external source or journal article.
+The writing style should be concise, jargon-free, consistent, and +pitched at the appropriate level to the intended target audience. All +technical terms and acronyms should be explained. However, don’t +reinvent the wheel by defining all the terms used, instead link to a +reliable external source or journal article.
+For more information about good writing style, please refer to these +style +guides.
Discuss with the group:
Not all READMEs must follow this structure. Always adapt the format +of your documentation to suit the specific needs of your audience.
Most people prefer to use a file format that allows you to create headers to organise the content into sections or chapters, which is much clearer for the reader.
-In this case, a Markdown document may be used. Markdown is a simple -mark-up language that allows you to format your text using symbols to -represent headers, bold text, bullet lists, etc. that are displayed to -the user in an appealing way. The Markdown syntax will be converted into -appealing visual styles that make your documentation more aesthetically -pleasing and easier to read.
+In this case, a Markdown +document may be used. Markdown is a simple markup language that +allows you to format your text using symbols to represent headers, bold +text, bullet lists, etc. that are displayed to the user in an appealing +way. The Markdown syntax will be converted into appealing visual styles +that make your documentation more aesthetically pleasing and easier to +read.
+A markup +language is a system of special characters that are used to +decorate or format pieces of plain text. The +syntax normally consists of symbols or tags that are used to +encode text, which means implying meaning to make it +more information-rich. It can be used to structure a documented into +sections to provide logical organisation so that it’s easier to +navigate.
+Typically, a markup language is edited in a similar way to a computer +programming language, and is rendered into a document +with various rich text formatting such as headers, bold face fonts, +etc.
+Use File
Explorer to rename
the file from README.txt to README.md.
README.md.Use the File
Manager to rename
the file from README.txt to README.md.
mv README.txt README.md
Use the Finder
to rename
the file from README.txt to README.md.
These may be used to add emphasis to parts of the text or highligh +key words and phrases. Using text formatting makes your software +documentation easier to skim-read, so researchers can quickly find the +part of the text that’s relevant for what they’re working on.
+Identify several key words in your README file. Highlight +them in using a bold font face.
+The Markdown syntax for bold font is to wrap the text in two
+asterixes **. This may be applied to single words or to
+phrases.
For example:
+ +Identify a bird based on the sound of its call.
+ +Identify a bird based on the sound of its +call.
+This will be rendered with the following apperearance:
@@ -1335,22 +1411,25 @@Code blockspi = 3.14 -
+++---Callout
++Markdown
You can learn more about writing documents using Markdown at Markdown Guide, a reference for using this syntax.
Remember, the README file is a first impression that research users -will receive for your software. Make them informative and user-friendly -to enhance the research experience for others and foster -collaboration.
+Remember, the README file is a first impression that +research users will receive for your software. A README contains a brief +description of the software, installation instructions, and a usage +guide. Make them informative and user-friendly to enhance the research +experience for others and foster collaboration. The writing style should +be concide, clear, and explain technical terms. Use diagrams and +screenshots for clarity.
@@ -1363,23 +1442,27 @@Key Points
users on installation, usage, and understanding its capabilities.- Consider the user’s technical background; write clearly and avoid jargon.
-- A README contains a brief description of the software, installation -instructions, and a usage guide.
-- The writing style should be concide, clear, and explain technical -terms.
-- Use diagrams and screenshots for clarity.
- Markdown is a recommended format for creating headers, bold text, bullet points, etc.
Further resources +
+
+For more information about writing basic software documentation, +please review the following materials:
++
-- Raphael Pierzina Hi, +my name is README! +
+
Content from Documentation strings
+ -->Content from Documentation strings
Last updated on 2024-09-12 | @@ -1460,7 +1543,7 @@
In R, we use a comment with a single quote #' to specify
a documentation string for a function.
oddsong.R;Let’s view the help text for an in-built function
abs() that finds the absolute value of a number.
These code examples can be used as automatic tests using the doctest module which is built into Python.
@@ -1753,7 +1836,7 @@There are several different standards for documentation strings. A standard is a convention that determines how @@ -3420,7 +3503,7 @@
On Windows operating systems, press the Windows key and type in “command”. The start menu will find the “Command Prompt” app. Press Enter or click on the Command Prompt icon to launch the @@ -3440,7 +3523,7 @@
On Ubuntu, press Ctrl + Alt + T to open a terminal.
You can also open Dash and search for “Terminal”. For detailed
instructions, please read Opening
@@ -3455,7 +3538,7 @@ BASH
bob@myUbuntuPC:~$
Please read Open or quit Terminal on Mac on the Terminal User Guide for macOS.
@@ -3489,7 +3572,7 @@On Windows, the dir command is used to list the contents of a directory. When you enter this command and press Enter
@@ -3519,7 +3602,7 @@To show the contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
location.
README.txtThe macOS terminal is very similar to the Linux one. To show the
contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
@@ -3569,7 +3652,7 @@
When using shell commands, we use the words option, flag, and arguments to describe @@ -3598,7 +3681,7 @@
In the Windows command line, we use the /? argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the dir
@@ -3633,7 +3716,7 @@
In the Linux command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -3662,7 +3745,7 @@
In the macOS command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -3714,7 +3797,7 @@
This is a mechanism that tells Python how we want users to interact with our software.
@@ -3759,7 +3842,7 @@When you run the python -m oddsong command, Python runs
the main module as a script.
When we run our script as before, it will run like normal with no change in behaviour.
@@ -3929,7 +4012,7 @@The code now looks something like that shown below.
We can achieve this in our example script by adding a
help string.
We define the description when creating our argument parser object.
diff --git a/instructor/cli.html b/instructor/cli.html index 601a82f..fe6d6a4 100644 --- a/instructor/cli.html +++ b/instructor/cli.html @@ -386,7 +386,7 @@On Windows operating systems, press the Windows key and type in “command”. The start menu will find the “Command Prompt” app. Press Enter or click on the Command Prompt icon to launch the @@ -406,7 +406,7 @@
On Ubuntu, press Ctrl + Alt + T to open a terminal.
You can also open Dash and search for “Terminal”. For detailed
instructions, please read Opening
@@ -421,7 +421,7 @@ BASH
bob@myUbuntuPC:~$
Please read Open or quit Terminal on Mac on the Terminal User Guide for macOS.
@@ -454,7 +454,7 @@On Windows, the dir command is used to list the contents of a directory. When you enter this command and press Enter
@@ -484,7 +484,7 @@To show the contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
location.
README.txtThe macOS terminal is very similar to the Linux one. To show the
contents of a directory on a Linux system, we use the ls
command which lists information about the files in the current
@@ -533,7 +533,7 @@
When using shell commands, we use the words option, flag, and arguments to describe @@ -562,7 +562,7 @@
In the Windows command line, we use the /? argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the dir
@@ -597,7 +597,7 @@
In the Linux command line, we use the --help argument to
instruct the computer to print the help information that that command.
To see helpful reference information for using the ls
@@ -626,7 +626,7 @@