FEAT: move image sharing documentation from gitlab repo to docs #82

dwheel7 · 2025-12-03T19:16:47Z

Pull Request

Intent

take documentation on sharing images in openstack from our gitlab repo to the docs site

Proposed Changes

add new page of documentation and updated nav to link to new page

jprorama · 2025-12-10T17:14:30Z

docs/openstack/share_image.md

+# Share an Image in Openstack
+
+You can share an image from your project with a collaborator in a different project in OpenStack cloud so you can both launch instances using the same image.  As the owner of the image, you can revoke the sharing privilege at any time.  You can also use these methods to share an image with yourself in other projects, just think of yourself as the collaborator.
+


Let's list the different types of state "private, shared, community, public" and provide some guidance on what they mean. Eg. All images are private by default. Public are available to any user on openstack, typically reserved for base OS images. Submit a support request to make an image public. To share images across projects you can use either set an image to either shared or community. A shared image requires that you explicitly specify which projects get access. This typ e of sharing is easier to manage using the openstack cli. A community image will be available to other projects but won't be listed among the default images in the UI. The community image is convenient but should not be used if you have any private credentials on an image (eg. a DB user/password).

Let's add a section on how to set the sharing in the UI and how you can use community images during instance creation in the Dashboard.

I might be missing something because of how my account is set up but I don't think there is anything different to do to use a community image versus a public/private one in instance setup. They just show in the list with the others

Including a screenshot like this will help readers build a mental model that matches your description. Highlight the relevant entry or entries using a red box.

Remember that some readers have low or no vision. Explicitly describe in the introductory text what you intend to show in the image so screen readers can make the (salient) image content perceivable.

Images also need alt text which describes what is in the image (as opposed to what the image shows).

Body text description might be like the following.

The image below shows an example of how VM disk images are tabulated in the OpenStack Horizon dashboard. Shared images are denoted with the text "Shared" in the XXX column. In the image, the shared images have been enclosed in a red box.

Alt text might be like the following.

![List of VM disk images in Horizon dashboard.](images/image.png)

Tools I use:

Flameshot for screen captures: https://flameshot.org/, lets you annotate before saving the image with a very convenient UI.

GIMP for image manipulation: https://www.gimp.org/

wwarriner

Great start!

Stylistic consistency is key. A key goal of documentation is ease of use, which means minimizing the mental workload of the reader in understanding our docs. Part of that is ensuring consistent style: voice, tense, and mood. I've left specific comments, but didn't mark every instance of inconsistency, so you'll need to review each part.

I recommend sticking to what "active, present imperative" style. It is very easy to read and understand.

Source the openrc file from your openstack project.

wwarriner · 2025-12-10T16:59:02Z

docs/openstack/share_image.md

+
+You can share an image from your project with a collaborator in a different project in OpenStack cloud so you can both launch instances using the same image.  As the owner of the image, you can revoke the sharing privilege at any time.  You can also use these methods to share an image with yourself in other projects, just think of yourself as the collaborator.
+
+**Prerequisites:**


Prefer headings to emphasis. Surprised markdownlint didn't catch this one.

## Level 2 ATX Heading

updated to header

wwarriner · 2025-12-10T16:59:05Z

docs/openstack/share_image.md

@@ -0,0 +1,98 @@
+# Share an Image in Openstack
+
+You can share an image from your project with a collaborator in a different project in OpenStack cloud so you can both launch instances using the same image.  As the owner of the image, you can revoke the sharing privilege at any time.  You can also use these methods to share an image with yourself in other projects, just think of yourself as the collaborator.


Our convention is to use only a single space character between sentences. We don't have a linter for it yet.

wwarriner · 2025-12-10T17:11:17Z

docs/openstack/share_image.md

+
+**Prerequisites:**
+
+- You will need to set up the OpenStack CLI to work with the project where the image to be shared is located.


Let's use consistent tense and mood within an article.

This bullet has "You will need" which is future tense, indicative mood (makes a statement about the future state of reality).

The next bullet has "Source the file" which is present tense, imperative mood.

For instructions in technical documentation, imperative mood works best as it is direct and to the point. It's something we're working on in the docs.

Simply remove "You will need to" from the start of the sentence and the subject changes from "You" to "OpenStack CLI", the primary verb changes from "need" to "set", and the statement becomes present imperative.

Decent article about this: https://www.theenglishbureau.com/blog/verb-moods/

I also recommend splitting the instruction into two parts. The first part is the actual instruction to use.

Set up the OpenStack CLI by running the following commands.

The second part of the sentence is explanation for the instruction. This is good to have, but it should be a separate sentence.

updated verbiage

wwarriner · 2025-12-10T17:15:53Z

docs/openstack/share_image.md

+    source <PATH_TO_YOUR_OPENRC_FILE>
+    ```
+
+- Find the ID of the target project you want to share the image with


This is a stylistic choice, so consider it a convention. When introducing a non-prose feature, like a code block, use complete sentences and ending punctuation. You've got the complete sentence, but are missing a full stop . character.

You can also introduce with a sentence ending in a colon character :, but you should be consistent within an article. I personally prefer full stops.

updated to switch to full stop throughout

wwarriner · 2025-12-10T18:35:17Z

docs/openstack/share_image.md

+    openstack project list
+    ```
+
+This information can also be found via the OpenStack UI


Which info? Is this meant to be part of the last bullet, or describing the entire subsection?

updated to specify reference

wwarriner · 2025-12-10T18:36:05Z

docs/openstack/share_image.md

+
+## Accept a Shared Image
+
+- Source the Target Project's Credentials: The user in the target project needs to source the appropriate OpenStack credentials for their project.


End with a full stop instead.

Source the Target Project's Credentials.

updated for full stop

wwarriner · 2025-12-10T18:36:12Z

docs/openstack/share_image.md

+## Accept a Shared Image
+
+- Source the Target Project's Credentials: The user in the target project needs to source the appropriate OpenStack credentials for their project.
+- Accept the Shared Image: The target project user then accepts the shared image using its ID:


Same as above.

wwarriner · 2025-12-10T18:36:58Z

docs/openstack/share_image.md

+
+## Unshare an Image (Optional)
+
+If you would like to remove a project from having access to the image, you can do the following


"revoke a project's access to an image"

updated wording

wwarriner · 2025-12-10T18:37:21Z

docs/openstack/share_image.md

+
+If you would like to remove a project from having access to the image, you can do the following
+
+- An image's owner can see which projects have access to the image:


"The image owner"

updated wording

wwarriner · 2025-12-10T18:38:01Z

docs/openstack/share_image.md

+    openstack image member list <IMAGE_NAME_OR_ID>
+    ```
+
+- The owner can unshare an image like this:


Stay consistent with your earlier present imperative style with full stops.

updated to full stop

feat: move sharing documentation from gitlab repo to docs

0a58c48

jprorama reviewed Dec 10, 2025

View reviewed changes

feat: add visibility table. add web ui instructions and pictures

a00342a

wwarriner requested changes Dec 10, 2025

View reviewed changes

style: correcting style inconsistencies and header style

220029b

		# Share an Image in Openstack

		You can share an image from your project with a collaborator in a different project in OpenStack cloud so you can both launch instances using the same image. As the owner of the image, you can revoke the sharing privilege at any time. You can also use these methods to share an image with yourself in other projects, just think of yourself as the collaborator.


		You can share an image from your project with a collaborator in a different project in OpenStack cloud so you can both launch instances using the same image. As the owner of the image, you can revoke the sharing privilege at any time. You can also use these methods to share an image with yourself in other projects, just think of yourself as the collaborator.

		Prerequisites:

		@@ -0,0 +1,98 @@
		# Share an Image in Openstack

		You can share an image from your project with a collaborator in a different project in OpenStack cloud so you can both launch instances using the same image. As the owner of the image, you can revoke the sharing privilege at any time. You can also use these methods to share an image with yourself in other projects, just think of yourself as the collaborator.


		Prerequisites:

		- You will need to set up the OpenStack CLI to work with the project where the image to be shared is located.


		## Accept a Shared Image

		- Source the Target Project's Credentials: The user in the target project needs to source the appropriate OpenStack credentials for their project.


		## Unshare an Image (Optional)

		If you would like to remove a project from having access to the image, you can do the following


		If you would like to remove a project from having access to the image, you can do the following

		- An image's owner can see which projects have access to the image:

FEAT: move image sharing documentation from gitlab repo to docs #82

Are you sure you want to change the base?

FEAT: move image sharing documentation from gitlab repo to docs #82

Uh oh!

Conversation

dwheel7 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Intent

Proposed Changes

Uh oh!

jprorama Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wwarriner Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wwarriner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dwheel7 commented Dec 3, 2025 •

edited

Loading

jprorama Dec 10, 2025 •

edited

Loading

wwarriner Dec 10, 2025 •

edited

Loading