Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-28 16:59:40 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update doc style guide and instructions

Browse Source 
- Explain why image linking is important
- Improve wording
- Fix link
- Minor improvements
This commit is contained in:
Andrew David Wong 2021-07-10 12:52:48 -07:00
parent ce900bfea7
commit f608865417
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
2 changed files with 20 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
developer/general/documentation-style-guide.md
View File

@ -66,11 +66,19 @@ breaks:
### Image linking
See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images).
See [how to add images](/doc/how-to-edit-the-documentation/#how-to-add-images)
for the required syntax. This will make the image a hyperlink to the image
file, allowing the reader to click on the image in order to view the full image
by itself. This is important. Following best practices, our website has a
responsive design, which allows the website to render appropriately across all
screen sizes. When viewing this page on a smaller screen, such as on a mobile
device, the image will automatically shrink down to fit the screen. If visitors
cannot click on the image to view it in full size, then, depending on their
device, they may have no way see the details in the image clearly.
Link only to images in
[qubes-attachment](https://github.com/QubesOS/qubes-attachment). Do not link to
images on other websites.
In addition, make sure to link only to images in the
[qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository. Do
not attempt to link to images hosted on other websites.
### HTML and CSS
@ -232,9 +240,10 @@ instead. However, *linking* to external documentation from
[qubes-doc](https://github.com/QubesOS/qubes-doc) is perfectly fine. Indeed,
the maintainers of the [Qubes Community](https://github.com/Qubes-Community)
project should regularly submit PRs against the documentation index (see [How
to edit the documentation index](#how-to-edit-the-documentation-index)) to add
and update Qubes Community links in the "External Documentation" section of the
documentation table of contents.
to edit the documentation
index](/doc/how-to-edit-the-documentation/#how-to-edit-the-documentation-index))
to add and update Qubes Community links in the "External Documentation" section
of the documentation table of contents.
The main difference between **core** (or **official**) and **external** (or
**community** or **unofficial**) documentation is whether it documents software

8
developer/general/how-to-edit-the-documentation.md
View File

@ -126,7 +126,7 @@ pull request, we'll post a comment explaining why we can't.
The source file for the [documentation index (a.k.a. table of contents)](/doc/)
is
[_data/doc-index.yml](https://github.com/QubesOS/qubesos.github.io/blob/master/_data/doc-index.yml).
[doc-index.yml](https://github.com/QubesOS/qubesos.github.io/blob/master/_data/doc-index.yml).
Editing this file will change what appears on the documentation index. If your
pull request (PR) adds, removes, or edits anything that should be reflected in
@ -135,9 +135,9 @@ request against this file.
## How to add images
To add an image to a page, use the following syntax in the main document. This
will make the image a hyperlink to the image file, allowing the reader to click
on the image in order to view the image by itself.
To add an image to a page, use the following syntax in the main document (see
[here](/doc/documentation-style-guide/#image-linking) for why this syntax is
important).
```
[![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png)