Minor fixes to the Documentation docs

flybywiresim · Nov 3, 2024 · 858a9f1 · 858a9f1
1 parent 098eeb7
commit 858a9f1
Showing 1 changed file with 48 additions and 37 deletions.
diff --git a/docs/dev-corner/documentation-guide/writing-documentation.md b/docs/dev-corner/documentation-guide/writing-documentation.md
@@ -100,56 +100,67 @@ Below is an example of our current use case in the FlyByWire Documentation Proje
 ### Writing Good Documentation
 
 - Write documentation professionally and clearly.
-- Write for the targeted audience (Sim Beginner, Sim Veteran, Developers, etc.) and don't assume too much pre-knowledge on the reader's side.
-- Use the full availability of features baked into [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/){target=new} to create readable and well formatted guides.
-- Add illustrations where appropriate. Make sure you optimize images to be as small as possible (resize to their actually used size and use JPG Compression (50% is mostly ok)).
+- Write for the targeted audience (Sim Beginner, Sim Veteran, Developers, etc.) and don't assume too much pre-knowledge 
+  on the reader's side.
+- Use the full availability of features baked into 
+  [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/){target=new} to create readable and well formatted 
+  guides.
+- Add illustrations where appropriate. Make sure you optimize images to be as small as possible (resize to their 
+  actually used size and use PNG Compression).
   See [Image Assets Process](#image-assets-process) for more information.
 - Ensure relevant filenames are web-friendly slugs.
 - Don't hesitate to get feedback from the FlyByWire Documentation Team early and often.
 - Proofread your work carefully before marking "Ready for Review".
 
 ### Image Assets Process
 
-- Create the image (e.g. screenshots)
+- Create the image as PNG (e.g. screenshots) with the highest resolution possible
 - Edit the image (e.g. add comments, lines, boxes, arrows, etc.)
-    - If you think the original is worth it store it in `/src/assets` - but most images aren't worth it as screenshots are quickly retaken (Keeping a local copy of all your screenshots
-      is good practice just in case - but it is not worth to clutter the repo with them)
-- Put the edited image in the folder for the topic - e.g. `\docs\pilots-corner\assets\advanced-guides\vnav` for images related to the VNAV topic
+    - If you think the original is worth it store it in `/src/assets` - but most images aren't worth it as screenshots 
+      are quickly retaken (Keeping a local copy of all your screenshots is good practice just in case - but it is not 
+      worth to clutter the repo with them)
+- Put the edited image in the folder for the topic - e.g. `\docs\pilots-corner\assets\advanced-guides\vnav` for images 
+  related to the VNAV topic
 - Link the image in the markdown document - decide on the size you need (See admonition below for references)
-- Please lazy load images that are not in the viewport (e.g. images at the bottom of the page) - this is done by adding `loading=lazy` to the image tag.
+- Please lazy load images that are not in the viewport (e.g. images at the bottom of the page) - this is done by adding 
+  `loading=lazy` to the image tag.
+
    ```md title="Sample Image Markdown with Lazy Loading"
     ![image](directory/image.png){loading=lazy}
    ```
 
-    !!! tip ""
-        Width of images on docs based on the responsive layout.
-
-        - Change the size according to the table - max width is 826 px
-        - Compress the png image with a tool - [Website Planet Image Compressor](https://www.websiteplanet.com/webtools/imagecompressor/)
-        - Make sure size and quality are good - usually < 100 kB
-
-          | Size | Width  |
-          |:-----|:-------|
-          | 100% | 826 px |
-          | 95%  | 785 px |
-          | 90%  | 743 px |
-          | 85%  | 702 px |
-          | 80%  | 661 px |
-          | 75%  | 620 px |
-          | 70%  | 578 px |
-          | 65%  | 537 px |
-          | 60%  | 496 px |
-          | 55%  | 454 px |
-          | 50%  | 413 px |
-          | 45%  | 372 px |
-          | 40%  | 330 px |
-          | 35%  | 289 px |
-          | 30%  | 248 px |
-          | 25%  | 206 px |
-          | 20%  | 165 px |
-          | 15%  | 124 px |
-          | 10%  | 83  px |
-          | 5%   | 41  px |
+!!! tip ""
+    Width of images on docs based on the responsive layout.
+
+    - Change the size according to the table - max width is 826 px
+    - Compress the png image with a tool - [Shortpixel Image Compressor](https://shortpixel.com/online-image-compression)
+    - Make sure size and quality are good - usually < 100 kB
+    - All images can be clicked and zoomed out to the original size - so if you have a lot of details in the image, 
+      you can make it smaller and let the user zoom in if needed. The limit is a reasonable size of the image.  
+
+    | Size     | Width   |
+    |:---------|:--------|
+    | zoomable | 1024 px |
+    | 100%     | 826 px  |
+    | 95%      | 785 px  |
+    | 90%      | 743 px  |
+    | 85%      | 702 px  |
+    | 80%      | 661 px  |
+    | 75%      | 620 px  |
+    | 70%      | 578 px  |
+    | 65%      | 537 px  |
+    | 60%      | 496 px  |
+    | 55%      | 454 px  |
+    | 50%      | 413 px  |
+    | 45%      | 372 px  |
+    | 40%      | 330 px  |
+    | 35%      | 289 px  |
+    | 30%      | 248 px  |
+    | 25%      | 206 px  |
+    | 20%      | 165 px  |
+    | 15%      | 124 px  |
+    | 10%      | 83  px  |
+    | 5%       | 41  px  |
 
 ### Style