Skip to content

Instantly share code, notes, and snippets.

@astrojuanlu

astrojuanlu/conda-guide-rtd-notes.md

Last active February 28, 2021 12:40
Show Gist options
  • Save astrojuanlu/90c9c87457a86802d18469eeb435bc98 to your computer and use it in GitHub Desktop.
Save astrojuanlu/90c9c87457a86802d18469eeb435bc98 to your computer and use it in GitHub Desktop.
Download ZIP
Notes on writing a conda guide for Read the Docs
Raw
conda-guide-rtd-notes.md

Project

a guide on working with conda & RTD. Noting things like how to use conda-forge, and the best practices for using conda and pip together.

The audience

  • Who are they?

Data Scientists, Data Engineers and Developers. Heterogeneous level of programming skills.

  • What do they need?

To deploy the documentation of their software package using conda and Sphinx on Read the Docs.

  • Where will they be reading

From their desktop computers or laptops.

  • When will they be reading?

Any time. During working hours for those who get paid to write the docs, outside working hours for those who maintain a volunteer open source project.

  • Why will they be reading?

Either they have found some errors while trying to use conda on Read the Docs, or they haven't tried yet and want to figure out how to do it, or they don't know where to start.

  • How will they be reading?

Some of them will skim and Ctrl+F for the information they need, some others will read from top to bottom.

Content

  • How to configure the build to use conda
  • How to create your environment.yml file
    • Understand how the export works, and whether it should be written manually!

Writing

  • The active voice is easier to read and understand than the passive voice. Whenever possible, choose the active voice in your sentences.
  • Choose your words thoughtfully. Use the best word for the context. Include necessary details that make the text understandable and precise. Avoid overusing pronouns such as ‘it’ and ‘this’ as the reader may have difficulty identifying the antecedent.
  • Many technical documents provide instructions to the reader. Therefore, a task-based approach makes the content easier to understand
  • Always put the most important information in the main clause. The reader will better digest the priority information.
  • Refrain from writing in the first or second person. This means avoiding the use of the words “I”, “You”, or “We” in your writing.
  • "Write for translation"

Tips

  • Always write a document that is useful to the user.
  • Use mind maps to organize the information
  • As you prepare, continuously step back and view the document as the reader. Ask yourself: Is it accessible? How would they be using it? When will they be using it? Is it easy to navigate?

RTD Customer Journey

"Documenting projects is hard, hosting them shouldn’t be. Read the Docs was created to make hosting documentation simple." https://docs.readthedocs.io/en/stable/story.html

  1. Sign up
  2. Confirm email 3a. "Not sure how to start documenting your project? Check out the Getting Started Guide to learn how." https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html 3b. "Want to try a demo? Import our own demo project." https://readthedocs.org/dashboard/import/manual/demo/
  • "Your documentation is building" Easy peasy!
  • "Configure your documentation builds! Adding a .readthedocs.yml file..." https://docs.readthedocs.io/page/config-file/v2.html
    • conda is mentioned, but not explained 3c. "Import a project"
  • "Connect your account" or "Import manually" 3d. "Have a GitHub account? Connect your account and import your existing projects automatically."

And now, if I want to use conda, I'm on my own.

Timing

  • 1h gathering the information above
  • 20m setting up the development environment
  • 20m setting a test account, importing the demo project, and taking notes of the customer journey
  • 10m reading the configuration documentation
  • 10m exploring the rest of the RTD docs
  • 10m setting up the development environment for real after I found the install docs
    • And then realizing that it won't be necessary to see my local changes
  • 5m focusing on the existing conda docs
  • 1h reading conda docs

= 3h15m

  • 1h45m reading old issues to look for common problems, tips, tricks, and some context about the current status and the history of the decisions

= 5h

Inspiration

Relevant old issues

Other ideas

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment