Skip to content

User Documentation

Jump to bottom
Chris Meyer edited this page Mar 18, 2022 · 10 revisions

Here are some guidelines if you are already working on user documentation or want to contribute.

Documentation Scope

Nion Swift is a data visualization and processing application with data acquisition capabilities.

Documentation of instrument/microscope specific operations and some camera/acquisition related operations will not fit cleanly into the core user documentation and should instead be included with the instrumentation kit or more specific instrument related projects.

User documentation should apply to the current code in GitHub. We try to make minor releases every 4-8 weeks, so accepted changes will be published frequently.

If you are documenting a feature being developed on a branch or disabled by a feature flag, consider writing the documentation on a branch.

Documentation is needed for general description, installation, use, and scripting.

General Note

Please file issues for incomplete, inconsistent, difficult to understand, or out of date information for any of these steps. Feedback is important.

Getting Ready to Contribute

  1. Browse the Nion website to understand Nion's electron microscope product.
  2. Understand the purpose of Nion Swift and read the User's Guide (incomplete, but useful).
  3. Install Nion Swift and try to do some simple tasks (this is easier said than done; and this is where we will need some improved documentation!). You can download a drag-and-drop version of Nion Swift 0.16.1 for macOS, an installer of Nion Swift 0.16.1 for Windows, or you can follow the (more complicated) installation instructions on macOS, Windows, or Linux.
  4. Meet the development team via email or zoom, trade contact information (email, chat, zoom, optionally phone).
  5. Review expectations and state of the product with your mentor or manager.

Where does the User Documentation Live?

The user documentation currently lives alongside the source code in GitHub. It is written in RestructuredText markup, processed automatically when updated on GitHub, and published to the readthedocs website.

What Can You Do?

The existing documentation is minimal, so there are many ways to contribute!

As a rough guide, this is how we expect user documentation to evolve over time.

  1. Little or no documentation (where we are today)
  2. Basic text explanation of capabilities
  3. Add how-to guides within appropriate sections for common use cases
  4. Add screenshots (for stable features first)
  5. Add video tutorials (for extremely stable features)
  6. Translate documentation to other languages

The easiest way to contribute is to file issues for anything you find confusing or wrong, particularly when you start the software or when using a new feature. There are many missing pieces, so don't go overboard.

You can also write documentation. We recommend starting small and basic and then expanding as your skills grow.

Ideally you can configure the documentation build and run it locally on your own computer and then submit a pull request via GitHub. This allows us to review the submission, make comments, and merge it with less work and it much preferred.

However, at this early stage, we are also happy to take submissions as un-styled (plain) text files and not include any styling. The best way is to follow the guidelines for RestructuredText markup.

Another alternative would be to write your text on a personal Wiki page such as that provided by GitHub and then we can copy from the Wiki page.

If you are including images (not recommended at this stage), please use a pull request.

Please do NOT submit Word documents or any other formatted text such as RTF, PDF, or Latex.

Documentation Styles

Documentation should be written in standard English with proper spelling and punctuation. If you find documentation which does not adhere to this standard, please file an issue or submit a pull request with the change.

As a quick stand-in for Nion Swift specific styles, the Blender style guide and markup guide are useful starting points.

Configuring the Documentation Build

Nion Swift uses Sphinx, a Python documentation generator, to produce documentation. The basic idea is that you will write documentation using Markdown syntax in text files and generate HTML files from the Markdown files. Nion Swift already is configured to automatically publish the resulting HTML files on the Nion Swift documentation site, hosted by readthedocs.org.

To configure the documentation build, you will first need to create a GitHub account.

Next you will need to download the GitHub Desktop application, launch it, and sign into your GitHub account. We suggest reading the documentation for GitHub Desktop. Git and GitHub are complex tools, so expect a learning curve.

Next, you will "Clone a Repository from the Internet...". Any easy way to do this is to visit the Nion Swift GitHub page and click on the green Code button and select "Open with GitHub Desktop". This will return you to GitHub desktop where you can specify a directory into which the project will be placed.

At this point, you have a copy of Nion Swift on your local machine. The basic workflow now is to modify the documentation files, render them to HTML on your local machine, and then do a "pull request" to the main project on GitHub when you are ready to submit your changes. A "pull request" is a request for the Nion Swift maintainers to review your documentation, give feedback, and ultimately merge your changes into the main project.

Next, you will have to install a new copy of Python 3.9 on your machine. Your machine may already contain a version of Python; however, we recommend installing a new copy using the Miniconda installer, so that you get the latest version and easily add additional packages without affecting the pre-installed Python in your operating system. We recommend using default/recommended values for any settings in the installer.

Once Python is installed you will need to launch a command line tool. On macOS and Linux, this is called Terminal. On Windows, you will use Command Prompt. Once you have launched the command line tool, you will need to enable the Python environment (aka the "conda environment").

(INCOMPLETE INSTRUCTIONS; WORK IN PROGRESS)

Embedding Images

  • Prefer macOS in "Light Mode Appearance" to capture screenshots. If screenshots are captured on Windows or Linux, be consistent within a page and/or documentation set.
  • On macOS, capture screenshots using Cmd-Shift-4, then select the desired screen area. The screenshot will be saved to your desktop.
  • On macOS, screenshots captured on retina displays will have twice the resolution you expect. This is desired, however, you will need to specify a width when including the graphics otherwise they will appear too large in the documentation. If the "screen width" shown during capture is 450px wide, the actual image file will be 900px. You will need to explicitly set the width to 450px (see below) to make it appear correctly. Also see additional notes about preferred image widths.
  • Try to ensure all screenshots on a page have similar scaling unless fundamentally different. i.e. a screenshot of the inspector and a screenshot of the toolbar should have the same scaling (50%) whereas a screenshot of the entire desktop would not fit into a web page at 50% resolution - it will need something more like 25% or scaling.
  • Aim for 50% scaling on normal UI screenshots (i.e. image is 900px, web page width should be 450px). Aim for 37.5%, 33%, 25% scaling if appropriate. For larger screenshots (desktop or entire window), use a max width of 640px but try to keep the same scaling if there are multiple larger screenshots on a particular page.
  • Store images in docs\graphics. Try to reuse images where possible. Name images uniformly using underscore. Include width. introduction_display_panel_900px.png, introduction_inspector_info_750px.png, etc.
  • Use PNG file format for screenshots since it is lossless and will make the UI look correct and avoid compression artifacts.
  • Use JPG file format for photos since it will be smaller and artifacts won't be a concern.
  • Include alt tag to name image in web metadata (see examples below).

Example of UI screenshot from upgrading.rst, image is 900px PNG.

.. image:: graphics/choose_project.png
  :width: 450
  :alt: Choose Project

Example of desktop screenshot from index.rst, image is 3010px PNG.

.. image:: graphics/workspace.png
  :width: 640
  :alt: The Swift Workspace
Clone this wiki locally