Bug 29712 - [DOCS] [Omnibus] Content development guide
Summary: [DOCS] [Omnibus] Content development guide
Status: ASSIGNED
Alias: None
Product: Koha
Classification: Unclassified
Component: Documentation (show other bugs)
Version: Main
Hardware: All All
: P3 enhancement (vote)
Assignee: David Nind
QA Contact: Testopia
URL: https://wiki.koha-community.org/wiki/...
Keywords:
Depends on: 29714 29751
Blocks: 23756
  Show dependency treegraph
 
Reported: 2021-12-16 15:18 UTC by David Nind
Modified: 2023-12-11 11:34 UTC (History)
3 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:


Attachments
Screenshot of generated version notes (47.08 KB, image/png)
2023-10-30 14:02 UTC, Caroline Cyr La Rose
Details
Screenshot of generated version notes with custom css (47.13 KB, image/png)
2023-10-30 14:04 UTC, Caroline Cyr La Rose
Details

Note You need to log in before you can comment on or make changes to this bug.
Description David Nind 2021-12-16 15:18:38 UTC
Omnibus bug for the creation of a content development guide for the documentation team.

It will include:

* a style guide: guidelines for writing clear and concise content, including grammar and word lists
* an information model: structures and guidelines to help us write different types of content consistently
* a content strategy: a plan outlining how we develop content, including the types of information products we create, the tools we use, and the processes we follow
Comment 1 Caroline Cyr La Rose 2023-09-21 18:36:48 UTC
Here are some notes that I took while I wrote documentation. It is what *I* do and is open to discussion

Style guide

GENERAL
-  When inserting links or references, have the text of the link be significant (also avoid links that say "click here"), for example
   -  preferred form: :ref:`create a new authorized value category <add-new-authorized-value-category-label>`
   -  non-preferred form: :ref:`create <add-new-authorized-value-category-label>` a new authorized value category
-  Use American English
-  Write 'system preference' in long form (rather than just 'preference')
-  Use 2nd person (you do this and that)

SCREENSHOTS
*-  I try to take general screenshots that can be reused in many places, for example, I will take a screenshot of all options in a menu rather than very specific screenshots of a single button/option
*-  I classify the screenshots in the module where they were taken rather than where the screenshot is used in the manual, for example, a screenshot of an OPAC message in the OPAC will be classified in the OPAC directory even if it is used in the patrons chapter to show how it looks to the patron when you add a message in their file

TITLES
-  Use verbs and present participle, for example
   -  preferred form: Adding an authorized value
   -  non-preferred form: Add an authorized value
   -  non-preferred form: Creation of an authorized value
-  Always add a label, so that this section can be referred to elsewhere

Descriptions
-  When describing a form, use a bullet list and each bullet should start with the label of the field, for example
   -  preferred form: Name: this is the name of the field as you want it to appear.
   -  non-preferred form: Enter the name as you want it to appear.
   -  non-preferred form: Enter the 'Name' as you want it to appear.

Formatting
-  Cut lines at 80 characters if possible (not always possible, esp. with tables)
-  If possible, do not cut ref links (I'm not sure if it changes anything, but my text editor doesn't highlight them if they are on multiple lines)
-  Follow bullet points with two spaces
-  End complete sentences with a period
-  Use single quotes, except if the content has an apostrophe
-  Use single quotes and capitalization for button names, for example
   -  preferred form: Click the 'Submit' button.
   -  non-preferred form: Click the submit button.


TBD
-  Which tense to use in the text?
   -  Present: the number of holds is displayed; the button is on the right
   -  Future: the number of holds will be displayed; you will see the button on the right
Comment 2 Katrin Fischer 2023-10-29 11:00:20 UTC
Hi Caroline, I think these are all good points! 

I was curious about how to mark the versions in the new one manual. I think we'd need possibly:

* Appears in version x
* Removed in version x
* Moved into <link> in version x

How to deal with backported features: do we give the exact version to the third number? 22.11.12? Or only the first 'big' release it went into?
Comment 3 Caroline Cyr La Rose 2023-10-30 13:58:49 UTC
I did some tests with directives and "admonitions" (this sounds so bad... like we did something wrong but anyway, it's what it's called).


This is what the code looks like

Tests for version notes

.. Admonition:: Version note
  
   This feature|button|option appears in version 23.05

.. Warning:: 

   This feature|button|option was removed in version 23.05  

.. Warning::

   This feature|button|option is deprecated as of version 23.05.
   Use :ref:`YXZ <administration-label>` instead.

.. Admonition:: Version note

   This feature|button|option was removed in version 23.05

.. Admonition:: Version note

   This feature|button|option was moved to :ref:`wherever <administration-label>` in version 23.05


And this is what it looks like once generated https://snipboard.io/fw3eX0.jpg 

I added some css to custom.css to change the colour if the title of the admonition is "Version note"

.rst-content .admonition-version-note {
  background: #dffcd7;
  }

.rst-content .admonition-version-note .admonition-title {
  background: #4a9b32;
  }

This is the result https://snipboard.io/THSpGn.jpg

Open to comments/suggestions
- Is "Version note" ok as a title?
- Do we prefer the green box or do we keep the blue (same as the Notes)
- Anything else?
Comment 4 Caroline Cyr La Rose 2023-10-30 14:02:23 UTC
Created attachment 158065 [details]
Screenshot of generated version notes

This is the rendering without the custom css. The boxes are the same colour as the "Notes", but the title says "Version note" instead.

It is the same as https://snipboard.io/fw3eX0.jpg I juste wanted to have the image attached to the bug just in case
Comment 5 Caroline Cyr La Rose 2023-10-30 14:04:20 UTC
Created attachment 158066 [details]
Screenshot of generated version notes with custom css

This is the rendering *with* the custom css. The boxes are green (I took the same green as the sidebar title part, but open to change it if you have a strong preference for something else)

It is the same as https://snipboard.io/THSpGn.jpg I just wanted to have the image attached to the bug just in case
Comment 6 Aude Charillon 2023-11-02 16:02:27 UTC
Regarding the versioning in the new manual: we'll be making decisions on this at the 29 November Documentation meeting. I'm making careful notes of Katrin's and Caroline's comments!

Thank you Caroline for your testing - it's brilliant to see the thing "for real".

I like the use of the warning note in orange for when something was removed. The admonition note - despite its grim name! - looks like what we need for new features. I particularly like that you have made it green to differentiate it from normal notes. I'm not sure whether it should have the header "Version note" or just "Version" but it's something else we can decide on in the Documentation meeting.
Comment 7 Caroline Cyr La Rose 2023-11-02 18:34:29 UTC
New rainbow test!! :)

https://snipboard.io/lTtcdQ.jpg

All the possible note directives (as found here https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives) and how they are styled in our theme, including the possible new "Version note" in custom green (name and colour to be discussed).

So far, we use mostly "Warning" and "Note" and a little bit of "Important" and "Tip".

I'd be interested to discuss (eventually) how to use each of these. I feel like most of the "Warning" notes do not warrant such a high priority and could be downgraded to "Important". Personally, I mostly used Warning before I knew Important existed...
Comment 8 Caroline Cyr La Rose 2023-11-02 19:10:59 UTC
Aude told me she liked the option to differentiate the "new in version" (koha green box) and "removed in version" (warning orange box).

This is a bit more complicated for the documenter, but I found a way to change the colour of the box for "new in version" and "removed in version", while keeping it a "Version note". https://snipboard.io/8nKLcM.jpg


We first have to declare the "roles" at the top of each page

.. role:: new-in-version
.. role:: removed-in-version

Then, before writing the note, we have to place it in a "container" and indent it

.. container:: new-in-version

   .. Admonition:: Version note

      New in version note.

.. container:: removed-in-version

   .. Admonition:: Version note

      Removed in version note.


And add some custom css (this is done only once, so it's ok, we just have to choose the colours)

.rst-content .new-in-version .admonition-version-note .admonition-title {
 background: #b342f5;
}

.rst-content .new-in-version .admonition-version-note {
  background: #e2bef7;
  }

.rst-content .removed-in-version .admonition-version-note .admonition-title {
 background: #fa46f1;
}

.rst-content .removed-in-version .admonition-version-note {
  background: #f7bef4;
  }


I think this is a bit too elaborate for us, but I would like to keep the "Warning" to actual warnings... Anyway, we'll be able to discuss this further at the meeting... 

Let me know if you have other ideas, I can prepare them for the meeting to have examples to look at.