Skill: Documenting software
Competency pathway
Ability to create clear, concise and comprehensive technical documentation that communicates the design, functionality and usage of a software product.
Related skills
Learning resources
| Name | Description | Language | Provider |
|---|---|---|---|
| Datasheets for Datasets | — | English | ACM Digital Library |
| Diataxis Framework | — | English | Diataxis |
| Model Cards for Model Reporting | — | English | Mitchel, M. et al |
| OLS Lesson | — | English | OLS |
| Project Documentation - The Turing Way | — | English | The Turing Way |
Computational tools
| Name | Description |
|---|---|
| Sphynx | A tool that makes it easy to create intelligent and beautiful documentation for Python projects. |
| Read the Docs | An open-source free software documentation hosting platform. |
| R Markdown | A file format for making dynamic documents with R. |
| Quarto | An open-source scientific and technical publishing system built on Pandoc. |
| MkDocs | A static site generator that's geared towards building project documentation. |
| JSDoc | A markup language used to annotate and document JavaScript code. |
| Javadoc | A documentation generator for the Java language for generating API documentation in HTML format. |
| CITATION.cff | A plain text file with human- and machine-readable citation information for software and datasets. |
| cffinit | A web application which helps users create a CITATION. cff file. |
Programming or data languages
| Name | Description |
|---|---|
| Markdown | A lightweight markup language for creating formatted text using a plain-text editor. |
Methodologies
| Name | Description |
|---|---|
| Code of Conduct | A code of conduct is a formal document outlining an organisation's, profession's, or group's values, ethical standards, and expected behaviors. |
| README | A text file containing information about the other files in a directory or software package. |
| Contribution guidelines | Rules and instructions for how people can help with a project (like open-source software or a publication), explaining the required formats, processes, and expectations for submitting work, ensuring quality, consistency, and clarity for both contributors and maintainers. |
| Docstrings | String literals that appear right after the definition of a function method class or module used for documentation. |