Documentation in scientific and academic publishing
On this page, we explore some of the many tools and practices that software documentation and academic writing share. If you are working within the field of science or academia, this page can be used as an introduction.
Documentation and technical writing are broad fields. Their tools and practices have grown relevant to most scientific activities. This includes building publications, books, educational resources, interactive data science, resources for data journalism and full-scale websites for research projects and courses.
Here’s a brief overview of some features that people in science and academic writing love about Read the Docs:
🪄 Easy to use
Documentation code doesn’t have to be written by a programmer. In fact, documentation coding languages are designed and developed so you don’t have to be a programmer, and there are many writing aids that makes it easy to abstract from code and focus on content.
Getting started is also made easy:
All new to this? Take the official Jupyter Book Tutorial
Curious for practical code? See Example projects
Familiar with Sphinx? See How to use Jupyter notebooks in Sphinx
🔋 Batteries included: Graphs, computations, formulas, maps, diagrams and more
Take full advantage of getting all the richness of Jupyter Notebook combined with Sphinx and the giant ecosystem of extensions for both of these.
Here are some examples:
Use symbols familiar from math and physics, build advanced proofs. See also: sphinx-proof
Present results with plots, graphs, images and let users interact directly with your datasets and algorithms. See also: Matplotlib, Interactive Data Visualizations
Graphs, tables etc. are computed when the latest version of your project is built and published as a stand-alone website. All code examples on your website are validated each time you build.
📚 Bibliographies and external links
Maintain bibliography databases directly as code and have external links automatically verified.
Using extensions for Sphinx such as the popular sphinxcontrib-bibtex extension, you can maintain your bibliography with Sphinx directly or refer to entries .bib files, as well as generating entire Bibliography sections from those files.
📜 Modern themes and classic PDF outputs
Use the latest state-of-the-art themes for web and have PDFs and e-book formats automatically generated.
New themes are improving every day, and when you write documentation based on Jupyter Book and Sphinx, you will separate your contents and semantics from your presentation logic. This way, you can keep up with the latest theme updates or try new themes.
Another example of the benefits from separating content and presentation logic: Your documentation also transforms into printable books and eBooks.
📐 Widgets, widgets and more widgets
Design your science project’s layout and components with widgets from a rich eco-system of open-source extensions built for many purposes. Special widgets help users display and interact with graphs, maps and more. Several extensions are built and invented by the science community.
⚙️ Automatic builds
Build and publish your project for every change made through Git (GitHub, GitLab, Bitbucket etc). Preview changes via pull requests. Receive notifications when something is wrong. How does this work? Have a look at this video:
💬 Collaboration and community
Science and academia have a big kinship with software developers: We ❤️ community. Our solutions and projects become better when we foster inclusivity and active participation. Read the Docs features easy access for readers to suggest changes via your git platform (GitHub, GitLab, Bitbucket etc.). But not just any unqualified feedback. Instead, the code and all the tools are available for your community to forge qualified contributions.
Your readers can become your co-authors!
Discuss changes via pull request and track all changes in your project’s version history.
Using git does not mean that anyone can go and change your code and your published project. The full ownership and permission handling remains in your hands. Project and organization owners on your git platform govern what is released and who has access to approve and build changes.
🔎 Full search and analytics
Read the Docs comes with a number of features bundled in that you would have to configure if you were hosting documentation elsewhere.
- Super-fast text search
Your documentation is automatically indexed and gets its own search function.
- Traffic statistics
Have full access to your traffic data and have quick access to see which of your pages are most popular.
- Search analytics
What are people searching for and do they get hits? From each search query in your documentation, we collect a neat little statistic that can help to improve the discoverability and relevance of your documentation.
- SEO - Don’t reinvent search engine optimization
Use built-in SEO best-practices from Sphinx, its themes and Read the Docs hosting. This can give you a good ranking on search engines as a direct outcome of simply writing and publishing your documentation project.
🌱 Grow your own solutions
The eco-system is open source and makes it accessible for anyone with Python skills to build their own extensions.
We want science communities to use Read the Docs and to be part of the documentation community 💞
Getting started: Jupyter Book
Jupyter Book on Read the Docs brings you the rich experience of computated Jupyter documents built together with a modern documentation tool. The results are beautiful and automatically deployed websites, built with Sphinx and Executable Book + all the extensions available in this ecosystem.
Here are some popular activities that are well-supported by Jupyter Book:
Publications and books
Course and research websites
Interactive classroom activities
Data science software documentation
Visit the gallery of solutions built with Jupyter Book »
Ready to get started?
All new to this? Take the official Jupyter Book Tutorial »
Curious for practical code? See the list of example projects »
Familiar with Sphinx? Read How to use Jupyter notebooks in Sphinx »
Examples and users
Read the Docs community for science is already big and keeps growing. The Jupyter Project itself and the many sub-projects of Jupyter are built and published with Read the Docs.
