diff --git a/config.yaml b/config.yaml index e5c2571..9a6360f 100644 --- a/config.yaml +++ b/config.yaml @@ -48,8 +48,8 @@ episodes: - readmes.md - docstrings.md - readable.md -- sites.md - contributors.md +- sites.md - cli.md # Information for Learners diff --git a/contributors.md b/contributors.md index 06ee933..32a45b4 100644 --- a/contributors.md +++ b/contributors.md @@ -49,11 +49,11 @@ Consider these questions amongst the group: ## Contribution guides -Contribution guidelines help users and understand how they can help to improve the software, whether that’s by submitting bug reports, suggesting new features, or writing better code and documentation. All of these aspects are vital to produce reusable research software. +Contribution guidelines help users and understand how they can **help to improve the software**, whether that’s by submitting bug reports, suggesting new features, or writing better code and documentation. All of these aspects are vital to produce reusable research software. -Potential collaborators should be able to easily find out how to take part and contribute. Developers should be encouraged to use appropriate communication channels to ask questions and inform others of proposed software changes. The contact details for the project administrator or committee should be available and they should be welcome and responsive to any queries. +Potential collaborators should be able to easily find out how to take part and contribute. Developers should be encouraged to use **appropriate communication channels** to ask questions and inform others of proposed software changes. The contact details for the project administrator or committee should be available and they should be welcome and responsive to any queries. -It’s important to explain how the project is managed so the process for evaluating new features and getting them implemented is clear, such as the code review and approval process. For many projects, a ticket system may be used to raise issues and suggest new features. Software developers often propose new code by creating a branch on the version control system (such as Git) and requesting for those changes to be merged into the main codebase. +It’s important to explain how the project is managed so the process for evaluating new features and getting them implemented is clear, such as the code review and approval process. For many projects, a **ticket system** may be used to raise issues and suggest new features. Software developers often propose new code by creating a branch on the version control system (such as Git) and requesting for those changes to be merged into the main codebase. Contribution guides will save you time in the long run, because it provides an on-ramp for people to get involved, prevents them from getting confused, and reduces the amount of incorrectly-submitted bug reports or requests for change, etc. @@ -73,12 +73,12 @@ The standard practice for authoring a contribution guide for a software project The specific contents of this file depend upon the kind of research project, but some useful information to provide typically includes: -- An introduction to the organisation and structure of the code, possibly including diagrams. -- Instructions to raising issues, suggesting new features, and proposing code changes. -- Links to additional documentation that's hosted elsewhere, such as a code of conduct or discussion forum. +- An introduction to the organisation and **structure of the code**, possibly including diagrams. +- Instructions to **raising issues**, suggesting new features, and proposing code changes. +- Links to **additional documentation** that's hosted elsewhere, such as a code of conduct or discussion forum. - A walkthrough to setting up a development environment, such as guidance on installing developer tools or other prerequisites. -On code hosting platforms such as GitHub, the contribution guide will be created automatically using this `CONTRIBUTING.md` Markdown file. +On code repository hosting platforms such as [GitHub](https://github.com), the [contribution guide](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors) will be created automatically using this `CONTRIBUTING.md` Markdown file. :::: challenge @@ -92,11 +92,11 @@ Create a new file called `CONTRIBUTING.md` and populate it with a few sentences. ## Software project governance -Project governance defines the scope and aims of a research software engineering project, and determines how decisions will be made and carried out. It sets out the processes and responsibilities that collaborators must understand to take part. This is something that should be considered when preparing a software management plan, as discussed in Module 1a of this course. This is important to make sure that questions of who does what, and how, are stated clearly so that everyone can understand and collaborate effectively to produce excellent research software. It's worthwhile to think about this early on in a project to avoid potential pitfalls later on! +Project governance defines the **scope and aims** of a research software engineering project, and determines how decisions will be made and carried out. It sets out the **processes and responsibilities** that collaborators must understand to take part. This is something that should be considered when preparing a software management plan, as discussed in Module 1a of this course. This is important to make sure that questions of who does what, and how, are stated clearly so that everyone can understand and collaborate effectively to produce excellent research software. It's worthwhile to think about this early on in a project to avoid potential pitfalls later on! ### Code of conduct -A code of conduct provides guidelines for the expected behaviour of people who are involved in the project. You may want to provide some general tips to create a productive community of researchers around the software, such as creating positive interactions between contributors, treat others with respect and dignity, and recommendations for processes for handling differences of opinion. +A code of conduct provides **guidelines for the expected behaviour** of people who are involved in the project. You may want to provide some general tips to create a productive community of researchers around the software, such as creating positive interactions between contributors, treat others with respect and dignity, and recommendations for processes for handling differences of opinion. This has the following advantages: @@ -106,9 +106,11 @@ This has the following advantages: For many working in a research context, there are additional considerations to ensure that institutional policies, ethics, and data protection regulations are carefully observed. These protocols are outside the scope of this document, but these factors should be clearly communicated to all contributors. -:::: tip +:::: callout -Many open-source research software projects adopt the [Contributor Covenant](https://www.contributor-covenant.org/), which can also be customised to suit the needs of your collaborators. +### Contributor Covenant + +Many open-source research software projects adopt the [Contributor Covenant](https://www.contributor-covenant.org/), which is a template charter that may be customised to suit the needs of your collaborators. :::: @@ -122,15 +124,15 @@ For people who are contributing code to the project, they'll need the following ### Technical documentation -System documentation is important for new contributors to familiarise themselves with the codebase and as a reference for existing engineers. There should be a concise description of how the system works from a more technical perspective, with the intended audience being software developers, rather than the research users. +System documentation is important for new contributors to **familiarise themselves with the codebase** and as a reference for existing engineers. There should be a concise description of how the system works from a more technical perspective, with the intended audience being software developers, rather than the research users. -An architecture diagram is an efficient way to provide a “map” to help developers to understand and navigate a complex system. +An **architecture diagram** is an efficient way to provide a “map” to help developers to understand and navigate a complex system. ### Coding conventions -Many projects following programming standards to manage code quality. A coding style guide will help to ensure consistency across all the code written as part of a collaborative project, which helps others to read and interpret the code, making it easier to maintain in the long run. The code style rules should cover things like the way to describe functions, how to indent code, and naming conventions for variables. +Many projects follow a set of programming standards to **manage code quality**. A coding style guide will help to ensure consistency across all the code written as part of a collaborative project, which helps others to read and interpret the code, making it easier to maintain in the long run. The code style rules should cover things like the way to describe functions, how to indent code, and naming conventions for variables. -This might include guidance and advice, or more strict rules as standards that are checked by a code linter. A code linter is an analysis tool that inspects code and checks for common errors and problems, producing a report for the developer to read and act upon. Common coding style standards include the PEP 8 style guide for the Python programming language and the tidyverse style guide in the R statistical language. +This might include guidance and advice, or more strict rules as standards that are checked by a **code linter**. A code linter is an analysis tool that inspects code and checks for common errors and problems, producing a report for the developer to read and act upon. Common coding style standards include the [PEP 8 style guide](https://peps.python.org/pep-0008/) for the Python programming language and the [tidyverse style guide](https://style.tidyverse.org/) in the R statistical language. ::::::::::::::::::::::::::::::::::::: discussion diff --git a/index.md b/index.md index fcc337d..29011a6 100644 --- a/index.md +++ b/index.md @@ -2,14 +2,14 @@ site: sandpaper::sandpaper_site --- +This course teaches **researchers how to document their software** effectively, making it accessible and understandable to others. Well-documented software promotes reproducibility, maintainability, and increased research impact through wider adoption and citation. -This course teaches researchers how to document their software effectively, making it accessible and understandable to others. It covers topics such as writing readable code and usage instructions. ## Course summary -Software documentation helps you and others to use your software successfully in the future and to read your code ensuring that its value is sustained. This course introduces the different ways to provide other researchers with useful documentation for your software. +Software documentation helps you and **others to use your software successfully** in the future and to read your code ensuring that its value is sustained. This course introduces the different ways to provide other researchers with useful documentation for your software. Research outputs often depend upon the code used to generate them. There are many advantages to making your code more readable. All kinds of research software, whether it’s code for data processing, analysis, and simulations, can be made more reproducible by providing clear context and instructions for using it. @@ -19,7 +19,7 @@ Well-documented software is easier to maintain and has greater sustainability, w This module is part of the "Coding best practices" section of the FAIR4RS training course. -This course will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience. +This module will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience. ### Course contents diff --git a/instructor-notes.md b/instructor-notes.md index d9a67aa..83f45ab 100644 --- a/instructor-notes.md +++ b/instructor-notes.md @@ -2,4 +2,5 @@ title: 'Instructor Notes' --- -This is a placeholder file. Please add content here. +The presentation course of this course should be modified depending on the target audience. +Many beginner coders in the research world will not need to know advanced skills such as how to automatically generate and deploy documentation websites, but some introductory material on this topic is here if required. diff --git a/introduction.md b/introduction.md index c09e4ad..34817fe 100644 --- a/introduction.md +++ b/introduction.md @@ -6,7 +6,7 @@ exercises: 2 :::::::::::::::::::::::::::::::::::::: questions -- How do we provide information to users of our research software? +- How do we **provide information** to users of our research software? - Why is documenting code useful for researchers? - What does well-documented software look like? @@ -15,7 +15,7 @@ exercises: 2 ::::::::::::::::::::::::::::::::::::: objectives - Understand the basic purpose of this course -- Learn the motivation for learning to document software +- Learn the **motivation** for learning to document software - Be introduced to good software documentation practices :::::::::::::::::::::::::::::::::::::::::::::::: @@ -42,11 +42,11 @@ Discuss positive or negative experiences with using research software: ### Advantages of good documentation -There are many advantages to writing guidance to go along with your research software. Software documentation helps yourself and others to use it successfully in the future and read your code ensuring that its value is sustained. +There are many **advantages to writing guidance** to go along with your research software. Software documentation helps yourself and others to use it successfully in the future and read your code ensuring that its value is sustained. -Research outputs often depend upon the code used to generate them. Clarity and confidence are essential in using code to perform calculations, simulations, or data analysis. All kinds of research processes and analysis pipelines can be made more **reproducible** by providing clear context and instructions for using it. +Research outputs often **depend upon the code** used to generate them. Clarity and confidence are essential in using code to perform calculations, simulations, or data analysis. All kinds of research processes and analysis pipelines can be made more **reproducible** by providing clear context and instructions for using it. -There are many advantages to making your code more readable. Well-documented software is easier to maintain and has greater sustainability, which means it can continue to be used and modified for a longer period of time, despite changes in technology. If software is more reusable then it encourages others to use it for their research, increasing the number of citations of that software and its overall research impact. +There are **many advantages** to making your code more readable. Well-documented software is easier to maintain and has greater **sustainability**, which means it can continue to be used and modified for a longer period of time, despite changes in technology. If software is more reusable then it encourages others to use it for their research, increasing the number of citations of that software and its overall research impact. :::: challenge @@ -58,18 +58,17 @@ Discuss the benefits of writing documentation for your research software. :::: -In the long run, it can help you to develop your own software engineering practice by getting into the habit of reflecting on what the purpose of the software is and to articulate what each component or module is for. +In the long run, it can help you to develop your own software engineering practice by getting into the habit of reflecting on what the **purpose of the software** is and to **articulate** what each component or module is for. -Writing a useful software package that is well-documented and can be reused in the future means that your code could take on a life of its own, with benefits that extend beyond yourself to your collaborators and other researchers in the future. High-quality documentation is a key part of ensuring a healthy software lifecycle. It can make the different between accidentally creating an abandoned piece of "gradware" (a slang term for mysterious code that a former student wrote and nobody else can use) and a successful long-term software project with lasting impact. +Writing a useful software package that is well-documented and can be reused in the future means that your code could take on a life of its own, with benefits that extend beyond yourself to your collaborators and other researchers in the future. High-quality documentation is a key part of ensuring a healthy **software lifecycle**. It can make the different between accidentally creating an abandoned piece of "gradware" (a slang term for mysterious code that a former student wrote and nobody else can use) and a successful long-term software project with lasting impact. ## When should I write documentation? -Now! Start writing and sharing documentation for your reseach code from the beginning of your project. It should be a -consideration in your _software management plan_, which is a concept discussed in the Module 1a on Software Lifecycle Planning. It's never too late to start documentaing an old code project. +Now! Start writing and sharing documentation for your reseach code **from the beginning** of your project. It doesn't have to be perfect straight away, but a first draft is more useful than nothing. It should be a consideration in your _software management plan_, which is a concept discussed in the Module 1a on Software Lifecycle Planning. Also, it's never too late to start documentaing an old code project. -This might include design notes, diagrams, or the various kinds of software documentation we'll discuss in this module. The best practice for modern, collaborative research involving digital methods and tools is to document your processes *early and often*. Not only will writing notes about your code help other people to read and use that code, it will clarify your thought process as you design your system, focussing your work on the important parts of the task at hand. +This might include design notes, diagrams, or the various kinds of software documentation we'll discuss in this module. The best practice for modern, collaborative research involving digital methods and tools is to document your processes **early and often**. Not only will writing notes about your code help other people to read and use that code, it will clarify your thought process as you design your system, focussing your work on the important parts of the task at hand. -Keep in touch with other developers and users of the research code and make a note of their feedback. Common questions and problems are a sign that there are issues that must be covered more clearly and in greater depth in the software documentation. Incorporate this feedback into the software documentation using the whichever method is most appropriate, following the guidance in this module. +**Keep in touch** with other developers and users of the research code and make a note of their feedback. Common questions and problems are a sign that there are issues that must be covered more clearly and in greater depth in the software documentation. **Incorporate this feedback** into the software documentation using the whichever method is most appropriate, following the guidance in this module. ## Examples @@ -118,7 +117,7 @@ This is a function with a name that doesn't explain what the code will do. There The logic of the calculation is also... rather cryptic. -Maybe the code works, maybe it doesn't but it could be made clearer and easier to maintain and modify in the future. +Maybe the code works, maybe it doesn't; but it could be made clearer and easier to maintain and modify in the future. ### Well-documented example @@ -192,7 +191,9 @@ calculate_sine <- function(angle) { } ``` -:::: challenge +::: + +:::: discussion Read and evaluate this code. @@ -202,11 +203,9 @@ Read and evaluate this code. :::: -::: - This time, the function name is a verb that describes what the code will attempt to do. The description of the function is also written out clearly in a note for the user. There are comment lines (starting with `#`) that explain the mathematicalal method used. Each variable has a descriptive, human-readable name, making the code more intuitive to read. An existing library is used to calculate the factorial, which means we can look up the usage for the `factorial()` function elsewhere. -This approach means that our code is much easier to interpret, maintain, and make changes to in the future. +This approach means that our code is much **easier to interpret**, maintain, and make changes to in the future. Of course, there may be some syntax in this example that is unfamiliar to you—but don't worry, we'll learn the basics in this course! @@ -217,14 +216,15 @@ Let's review real-world examples of the documentation for software packages that ### NumPy user guide NumPy is a mathematical package for the Python programming language that's used for linear algebra. -The [NumPy User Guide](https://numpy.org/doc/2.0/user/index.html#user) is a thorough website that organised into sections that cover the different aspects of using that package. +The [NumPy User Guide](https://numpy.org/doc/2.0/user/index.html#user) is a **thorough website** that organised into sections that cover the different aspects of using that package. + It includes a beginner's guide, tutorials for different use-cases, and in-depth write-ups of technical details of certain aspects of the code. Some of the content is written for a target audience with no assumed knowledge, while other parts are written as a reference for people with some background in mathematics and computer programming. ### ggplot2 documentation site ggplot2 is a package for the R statistical language that generates data visualisations and graphics. -The [ggplot2 documentation](https://ggplot2.tidyverse.org/index.html) has a simple, accessible layout and walks a new user through installing and getting up-and-running with the tool. +The [ggplot2 documentation](https://ggplot2.tidyverse.org/index.html) has a simple, accessible layout and **walks a new user through** installing and getting up-and-running with the tool. The page provides a "cheat sheet" which is a reference guide that lists commonly-used commands in an attractice two-page layout. The documentation site is moderate in scope and links to several external resources, such as online courses hosted elsewhere. diff --git a/md5sum.txt b/md5sum.txt index 1777adc..d40b38c 100644 --- a/md5sum.txt +++ b/md5sum.txt @@ -2,18 +2,18 @@ "CODE_OF_CONDUCT.md" "7dbd90cbbf0ff2b2e71220e41502029a" "site/built/CODE_OF_CONDUCT.md" "2024-08-16" "LICENSE.md" "f02fdcc64a49eab73e5b2d1255561742" "site/built/LICENSE.md" "2024-08-16" "SECURITY.md" "8a8cea030aafe5b2e6cce068b9f4b23c" "site/built/SECURITY.md" "2024-05-21" -"config.yaml" "b40191d8e29c40539a76774eae724b75" "site/built/config.yaml" "2024-09-25" -"index.md" "568532bd1e8c470d82e70a56a5130136" "site/built/index.md" "2024-08-14" +"config.yaml" "056dd5e8915e182ce0783d00d3f91974" "site/built/config.yaml" "2024-09-25" +"index.md" "e5c00425db8e16ea7c1159682288ab33" "site/built/index.md" "2024-09-25" "links.md" "8184cf4149eafbf03ce8da8ff0778c14" "site/built/links.md" "2024-05-20" -"episodes/introduction.md" "123579b22c95b6dcb57401b057235db5" "site/built/introduction.md" "2024-08-16" -"episodes/readmes.md" "de77cab83b0928556f7ee65c20f256cb" "site/built/readmes.md" "2024-09-19" +"episodes/introduction.md" "23d66a7a14cc9b5f2e8d9132c5da1fd3" "site/built/introduction.md" "2024-09-25" +"episodes/readmes.md" "d660735cb02afcdab0a4d3283dd2541b" "site/built/readmes.md" "2024-09-25" "episodes/docstrings.md" "63daea40b39344dffe8e870122e411c0" "site/built/docstrings.md" "2024-09-12" -"episodes/readable.md" "f19e6b940d27db524cd523a17f139a2c" "site/built/readable.md" "2024-09-19" -"episodes/sites.md" "c9455784fa5267c89f3137906f763334" "site/built/sites.md" "2024-09-12" -"episodes/contributors.md" "aaf64f98f3c2dd334ae5d211bb22bb74" "site/built/contributors.md" "2024-09-12" +"episodes/readable.md" "b1845a60dc09f3de849ad75b846c33cf" "site/built/readable.md" "2024-09-25" +"episodes/contributors.md" "adcb904b2e4cdc1c3f694b615004aa9d" "site/built/contributors.md" "2024-09-25" +"episodes/sites.md" "a6b0216d821619e02ece663adc4ffd59" "site/built/sites.md" "2024-09-25" "episodes/cli.md" "47329eb3a259e0b81c96c1233807e918" "site/built/cli.md" "2024-09-12" -"instructors/instructor-notes.md" "cae72b6712578d74a49fea7513099f8c" "site/built/instructor-notes.md" "2024-05-20" +"instructors/instructor-notes.md" "e0c08eb41de422f6f02b98312ff39b2d" "site/built/instructor-notes.md" "2024-09-25" "learners/acknowledgements.md" "a751175e5c52ccbf05f8291162bc2cea" "site/built/acknowledgements.md" "2024-08-16" -"learners/reference.md" "e9f7941bcc07451554f1eebfa238cdda" "site/built/reference.md" "2024-08-05" +"learners/reference.md" "f0c90e50d0246d38eb274700f544aa03" "site/built/reference.md" "2024-09-25" "learners/setup.md" "c9c366a420d545cb0c8baa53d779233a" "site/built/setup.md" "2024-07-19" "profiles/learner-profiles.md" "1145111179d18933c4be354eff7373a1" "site/built/learner-profiles.md" "2024-05-21" diff --git a/readable.md b/readable.md index aa41817..3269762 100644 --- a/readable.md +++ b/readable.md @@ -207,13 +207,25 @@ It's also a good idea not to use single-letter names such as `x` or `T` because ### Python -Classes use capitalised words +Classes use capitalised words, where each word in a phrase starts with an upper-case letter and there are no spaces between them. ```python class Bird: pass ``` +```python +class ConservationStatus: + """ + IUCN Red List of Threatened Species + """ + EX = "Extinct" + EW = "Extinct in the wild" + CR = "Critically Endangered" + EN = "Endangered" + LC = "Least Concern" +``` + Variables use lower case with underscores ```python @@ -236,6 +248,10 @@ Classes use capitalised words setClass("Bird", representation = character()) ``` +```R +setClass("ConservationStatus", representation = character()) +``` + Variables use lower case with underscores ```R @@ -401,7 +417,7 @@ add('cheese', 'cake') :::::::::::::::: solution -None of these code examples will cause an error because type hints are just passive labels that document our code. They don't enforce any type checking or rules that are asserted when the code is executed. This means that, while type hints are very useful for *static analysis* of code, where we learn something about a piece of software without running it. +None of these code examples will cause an error because type hints are just **passive labels** that document our code. They don't enforce any type checking or rules that are asserted when the code is executed. This means that, while type hints are very useful for *static analysis* of code, where we learn something about a piece of software without running it. ::::::::::::::::::::::::: diff --git a/readmes.md b/readmes.md index 4b67ad6..68c5cf2 100644 --- a/readmes.md +++ b/readmes.md @@ -7,31 +7,30 @@ exercises: 2 :::::::::::::::::::::::::::::::::::::: questions - How do we **introduce** our software to new researchers and developers? -- What is a README file? -- How do I write a README for my research code? -- What are the contents of a good README file? +- How do I structure the basic notes for my research code? +- What are the contents of good documentation? :::::::::::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::: objectives -- Explain why and how to write a README file for research software -- Learn how to structure a README file into sections +- Explain why and how to write a **README file** for research software +- Learn how to **structure** documentation into sections - Understand the important components of a good README :::::::::::::::::::::::::::::::::::::::::::::::: ## What is a README file? -A README file is the first thing a user sees when they find your software. It should give them an approachable overview of the package, define what’s possible to achieve with this code, and get them started on the right track to use the software effectively for their research. +A README file is the **first thing a user sees** when they find your software. It should give them an approachable overview of the package, define what’s possible to achieve with this code, and get them started on the right track to use the software effectively for their research. -A README contains a brief introduction to the code and shows them how to get started using it. For larger packages, the README forms a concise beginner guide and might link to a more detailed user guide that is located elsewhere. +A README contains a **brief introduction** to the code and shows them how to get started using it. For larger packages, the README forms a concise beginner guide and might link to a more detailed user guide that is located elsewhere. -The **audience** for a README file is the end user. It's important to consider _the person_ will read your documentation, and to see things from their point of view. It may be someone who is unfamiliar with certain technical terms, or a researcher will less experience of advanced computing. A good approach is to imagine writing a manual for a new user who has never seen this software before. +The **audience** for a README file is the _end user_, such as a researcher. It's important to consider _the person_ will read your documentation, and to see things from their point of view. It may be someone who is unfamiliar with certain technical terms, or a researcher will less experience of advanced computing. A suitable approach is to imagine writing a manual for a new user who has never seen this software before. ## How to write a README -To start writing a README file, the simplest way is to just create an empty text file called `README.txt` and start writing. This file should be located in the directory (or folder) that contains your software project. +To start writing a README file, the simplest way is to **create an empty text file** called `README.txt` and start writing. This file should be located in the directory (or folder) that contains your software project. ::::::::::::::::::::::::::::::::: challenge @@ -98,21 +97,27 @@ The essentials contents of a README file are: - **Installation instructions** or a link to further information published elsewhere. - **Usage instructions**, ideally including a “quick start” guide with a few simple examples to get people up and running with your software package. -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. +It can be useful to **signpost** to related useful methods and 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. ::: callout ## Walk a mile in the user's shoes 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? +Imagine that 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? +::: + +::: discussion + +Consider your field of research and the technologies you commonly use. + +- What things are obvious to you that may not be clear to others? +- What **assumed knowledge** must you explain to new colleagues to get them up to speed? ::: -For research code, it’s often important to explain the context in which the software was written and the theory behind it. For example, many researchers write analysis packages or workflows that are based on previously-published research, statistical methods, or theoretical models for which citations can be provided. By including references to research papers we better help the users to understand the methods that are implemented by our software, which enables its users to properly cite their sources and increases the users’ confidence that you have applied those methods correctly. +For research code, it’s often important to **explain the context** in which the software was written and the theory behind it. For example, many researchers write analysis packages or workflows that are based on previously-published research, statistical methods, or theoretical models for which **citations** can be provided. By including references to research papers we better help the users to understand the methods that are implemented by our software, which enables its users to properly cite their sources and increases the users’ confidence that you have applied those methods correctly. ### Installation instructions @@ -132,15 +137,19 @@ Think about: ::: -For most research code, the user will need to install the programming language onto their computer, such as R or Python, so it’s useful to link to the download pages and provide a link to the package manager tools that are commonly used in those ecosystems. This might also include listing any prerequisites such as hardware or software that must be installed first, such as device drivers. +#### Installing prerequisites + +Most research code has several **dependencies**, such as libraries. The user will need to install the programming language onto their computer, such as R or Python, so it’s useful to link to the download pages and provide a link to the package manager tools that are commonly used in those ecosystems. This might also include listing any prerequisites such as hardware or software that must be installed first, such as device drivers. Consider how the installation method might differ for users of other common operating systems, such as Windows, Linux, and Mac OS. ### User guide -All software should include some short guidance on how to use it and what the main options and features are. This might be a “quick start” guide with simple examples of common use-cases, or a walkthrough that uses a sample data set. Explain how the software can be configured or customised, including examples of commonly-used options. If the software integrates with other tools or uses specific file formats for its input and output, it’s useful to explain this here too. It’s a good idea to include links to further documentation if available. +All software should include some **short guidance on how to use it** and what the main options and features are. This might be a “quick start” guide with simple examples of common use-cases, or a walkthrough that uses a sample data set. -Many users will benefit from a frequently asked questions (FAQ) or troubleshooting notes, which describes common error messages, explains why they occur, and the steps to resolve them. +Explain how the software can be **configured or customised**, including examples of commonly-used options. If the software integrates with other tools or uses specific file formats for its input and output, it’s useful to explain this here too. It’s a good idea to include links to further documentation if available. + +Many users will benefit from a **frequently asked questions** (FAQs) or troubleshooting notes, which describes common error messages, explains why they occur, and the steps to resolve them. ::: callout @@ -150,7 +159,7 @@ The writing style should be concise, jargon-free, consistent, and pitched at the 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](https://www.writethedocs.org/guide/writing/style-guides/#traditional-writing-style-guide-resources). +For more information about the broad topic of improving your writing style, please review these [style guides](https://www.writethedocs.org/guide/writing/style-guides/#traditional-writing-style-guide-resources). ::: @@ -166,7 +175,7 @@ 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. +Always adapt the format of your documentation to suit the **specific needs** of your audience. ## Accessibility @@ -192,10 +201,10 @@ For more information on this topic, please see the following resources: ## Text formatting -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. +Most people prefer to use a file format that allows you to format text and create headers to organise the content into sections or chapters, which makes the content more **comprehensible for the reader**. In this case, a [Markdown](https://daringfireball.net/projects/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. +Markdown is a simple _markup language_ that indicates into **semantic labelling** (such as emphasis and structure) and visual styles that make your documentation more aesthetically pleasing and easier to navigate. It allows you to format your text using symbols to represent headers, bold text, bullet lists, etc. that are displayed to the user using their screen or other device, depending upon accessibility requirements. :::: spoiler @@ -253,27 +262,29 @@ mv README.txt README.md ::::::::::::::::::::::::::::::::::::::::::: -An example README file in Markdown format is shown below, in a file called `README.md` where .md is the file extension for Markdown files. +An example README file in Markdown format is shown below, in a file called `README.md` where ".md" is the file extension for Markdown files. ### Section headers -You can separate your document into hierarchical sections with headings using the `#` symbol. This makes your README easier to navigate. For example: +You can separate your document into **hierarchical sections** with headings using the `#` symbol. This makes your README easier to navigate. For example: ```markdown # Birdsong identification tool -This user guide provides instructions on how to use this birdsong identifier. The software is designed to assist users in identifying bird species based on their vocalisations. +This user guide provides instructions on how to use this birdsong +identifier. The software is designed to assist users in +identifying bird species based on their vocalisations. # Installation -To install this software... +To install this software, follow the steps below... # Usage -To use this package... +To use this package, start by configuring... ``` -The “#” symbol means that line will be converted into a header and displayed to the reader in a large, bold font. This makes it easier for the reader to find the part of your text they're looking for, just like having chapters in a book. +The hash `#` symbol means that line will be converted into a header and displayed to the reader in a large, bold font. This makes it easier for the reader to find the part of your text they're looking for, just like having chapters in a book. ::::::::::::::::::::::::::::::::: challenge @@ -335,7 +346,7 @@ These subheadings help the users to navigate the document. ::::::::::::::::::::::::::::::::: -If your code is published on GitHub, the home page of your code repository will display the README.md file, including a navigation menu that is automatically created to easily select the section of the document to view. +If your code is published on [GitHub](https://github.com), the home page of your code repository will [display the README file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes), including a [table of contents](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#auto-generated-table-of-contents-for-readme-files) that is automatically created to easily select the section of the document to view. !["This repository has a README file with chapters, making navigation easier."](fig/bootstrap-readme-chapters.png){alt="A screenshot of a GitHub repository with a drop-down navigation menu on the readme text box."} @@ -343,13 +354,12 @@ If your code is published on GitHub, the home page of your code repository will Here are some commonly-used text formatting options that can be used with Markdown syntax: -| Text display | Syntax | -| ----------------- | ------------------- | -| **Bold font** | `**Bold font**` | -| *Italic text* | `*Italic text*` | -| Underlined | `Underlined` | -| `Code block` | ``` `code block` ``` | -| [Hyperlink](https://sheffield.ac.uk) | `[Hyperlink](https://sheffield.ac.uk)` | +| Meaning | Example | Syntax | +| ------- | ---------- | ------------------- | +| Strong text | **Eastern towhee** | `**Eastern towhee**` | +| Emphasised text | *Pipilo erythrophthalmus* | `*Pipilo erythrophthalmus*` | +| Code block | `name = "Pipilo erythrophthalmus"` | ``` `name = "Pipilo erythrophthalmus"` ``` | +| Hyperlink | [Eastern towhee](https://en.wikipedia.org/wiki/Eastern_towhee) | `[Eastern towhee](https://en.wikipedia.org/wiki/Eastern_towhee)` | 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. @@ -363,19 +373,21 @@ Identify several _key words_ in your README file. Highlight them in using a bold 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: +For example, we can strongly emphasise a single word: ```markdown Identify a bird based on the **sound** of its call. ``` -Identify a bird based on the **sound** of its call. +> Identify a bird based on the **sound** of its call. + +Or emphasise a phrase: ```markdown **Identify a bird** based on the _sound of its call_. ``` -**Identify a bird** based on the _sound of its call_. +> **Identify a bird** based on the *sound of its call*. :::: @@ -386,22 +398,30 @@ Identify a bird based on the **sound** of its call. We can create a citation with appealing formatting by using the blockquote syntax in Markdown, which is similar to the method used in email. ```markdown -> This text is part of a blockquote. +> The eastern towhee (Pipilo erythrophthalmus) is a large New World +> sparrow. The taxonomy of the towhees has been under debate in +> recent decades, and formerly this bird and the spotted towhee +> were considered a single species, the rufous-sided towhee. ``` This will be rendered with the following apperearance: -> This text is part of a blockquote. +> The eastern towhee (Pipilo erythrophthalmus) is a large New World sparrow. +> The taxonomy of the towhees has been under debate in recent decades, +> and formerly this bird and the spotted towhee were considered a single species, the rufous-sided towhee. + +(This text was retrieved from the *Wikipedia* page on the [Eastern towhee +](https://en.wikipedia.org/wiki/Eastern_towhee).) ### Code blocks -If you'd like to present the user will examples of source code, use code fences to display the code in a special text box with syntax highlighting. For example: +If you'd like to present the user will examples of source code, use [code fences](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) to display the code in a special text box with syntax highlighting. To do this, wrap the code in three backticks `` ` ``. For example: - +````markdown ``` -pi = 3.14 +genus = "Struthio" ``` - +```` ::: callout @@ -430,3 +450,4 @@ Use diagrams and screenshots for clarity. For more information about writing basic software documentation, please review the following materials: - Raphael Pierzina [Hi, my name is README!](https://www.writethedocs.org/videos/eu/2017/hi-my-name-is-readme-raphael-pierzina/) +- Aleksandra Pawlik [Five top tips on documentation](https://www.software.ac.uk/guide/five-top-tips-documentation) diff --git a/reference.md b/reference.md index 333bba5..4592099 100644 --- a/reference.md +++ b/reference.md @@ -54,6 +54,9 @@ Operating system Documentation site : A software documentation website is a structured guide to using a library of research code. +Linter +: A system that analyses code for potential errors. + ## Further resources - Write the Docs, [A beginner’s guide to writing documentation](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/) diff --git a/sites.md b/sites.md index 3a9e524..e62fd39 100644 --- a/sites.md +++ b/sites.md @@ -50,17 +50,17 @@ There are many advantages to building a documentation site to provide a informat ### Advantages -These sites can work as hubs for collaboration, sharing the latest updates, and encouraging people to take up your system and get involved in improving it. The effort of setting one up will be rewarded in the long run because you will have created a valuable asset that will foster collaboration and knowledge sharing in your research community. +These sites can work as **hubs for collaboration**, sharing the latest updates, and encouraging people to take up your system and get involved in improving it. The effort of setting one up will be rewarded in the long run because you will have created a valuable asset that will foster collaboration and knowledge sharing in your research community. -A key foundation stone of modern digital research practices is the ability to replicate results by reproducing analysis workflows. Clear, thorough documentation of the research code ensures that researchers can repeat processes and verify results and other people's outputs. +A key foundation stone of modern digital research practices is the ability to **replicate results** by reproducing analytic workflows. Clear, thorough documentation of the research code ensures that researchers can repeat processes and verify results and other people's outputs. -Documentation sites are really useful for introducing new users to your software. It makes it much easier and faster for new users to get started using your software to boost their research. It's one of the most effective ways to create a user base that has a sophisticated understanding of the research code, which is essential for them to adapt it to the complex problems that often raise in research contexts. +Documentation sites are really useful for **introducing new users to your software**. It makes it much easier and faster for new users to get started using your software to boost their research. It's one of the most effective ways to create a user base that has a sophisticated understanding of the research code, which is essential for them to adapt it to the complex problems that often raise in research contexts. -They're also a valuable resource for your existing user base, enabling them to look up reference material or search the manual to find new capabilities they weren't aware of before. This will increase the potential for your software to accellerate the productivity of other research teams and boost scientific progress. +They're also a valuable resource for your existing user base, enabling them to look up reference material or search the manual to find new capabilities they weren't aware of before. This will increase the potential for your software to increase the productivity of other research teams. ### When to use one -Although the advantages are numerous, not all software packages require a comprehensive documentation website. However, for any code project that is growing in the number of collaborators, users, and technical complexity, consider coordinating the team to write one as soon as possible to help the project grow in a healthy manner. +Although the advantages are numerous, not all software packages require a comprehensive documentation website. However, for any code project that is growing in the number of collaborators, users, and technical complexity, consider coordinating the team to write one as soon as possible to help the project continue its' healthy growth. ::::::::::::::::::::::::::::::::::::: discussion @@ -75,11 +75,11 @@ Consider the following factors: ## Contents -Documentation pages contain comphrehensive information about a particular piece of research software. Think of it like a user manual for your car or an instruction guide for building a piece of furniature. +Documentation pages contain **comphrehensive information** about a particular piece of research software. Think of it like a user manual for your car or an instruction guide for building a piece of furniature. ### Research context -For research software, it may be important to explain the theoretical background or statistical methods that are used and explain the domain-specific assumptions that were made when the code was designed and written. It's good practice to provide a concise summary of the relevent concepts and link to external sources such as papers, books, and other websites for users to take a deeper dive into the principles and algorithms used. +For research software, it may be important to explain the **theoretical background** or statistical methods that are used and explain the domain-specific assumptions that were made when the code was designed and written. It's good practice to provide a concise summary of the relevant concepts and link to external sources such as papers, books, and other websites for users to take a deeper dive into the principles and algorithms used. ### Installation instructions