[Bug 29712] New: [DOCS] [Omnibus] Content development guide
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 Bug ID: 29712 Summary: [DOCS] [Omnibus] Content development guide Change sponsored?: --- Product: Koha Version: master Hardware: All URL: https://wiki.koha-community.org/wiki/Documentation_-_C ontent_Development_Guide OS: All Status: ASSIGNED Severity: enhancement Priority: P3 Component: Documentation Assignee: david@davidnind.com Reporter: david@davidnind.com QA Contact: testopia@bugs.koha-community.org 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 -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Depends on| |29714 Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29714 [Bug 29714] [DOCS] Git guide for documentation -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Blocks| |29751 Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29751 [Bug 29751] [DOCS] Document how linking from Koha to the manual works -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Depends on| |29751 Blocks|29751 | Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29751 [Bug 29751] [DOCS] Document how linking from Koha to the manual works -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |caroline.cyr-la-rose@inlibr | |o.com --- Comment #1 from Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> --- 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 -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 Aude Charillon <aude.charillon@ptfs-europe.com> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |aude.charillon@ptfs-europe. | |com -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #2 from Katrin Fischer <katrin.fischer@bsz-bw.de> --- 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? -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #3 from Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> --- 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? -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #4 from Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> --- Created attachment 158065 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=158065&action=edit 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 -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #5 from Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> --- Created attachment 158066 --> https://bugs.koha-community.org/bugzilla3/attachment.cgi?id=158066&action=edit 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 -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 Heather <heather_hernandez@nps.gov> changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |heather_hernandez@nps.gov -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #6 from Aude Charillon <aude.charillon@ptfs-europe.com> --- 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. -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #7 from Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> --- 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#dire...) 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... -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 --- Comment #8 from Caroline Cyr La Rose <caroline.cyr-la-rose@inlibro.com> --- 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. -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 Aude Charillon <aude.charillon@ptfs-europe.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Blocks| |23756 Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=23756 [Bug 23756] Appendix for workflows -- You are receiving this mail because: You are watching all bug changes.
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29712 David Nind <david@davidnind.com> changed: What |Removed |Added ---------------------------------------------------------------------------- Blocks| |40232 Referenced Bugs: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=40232 [Bug 40232] [DOCS] Use Vale to "lint" the manual against the style guide/content development guide rules -- You are receiving this mail because: You are watching all bug changes.
participants (1)
-
bugzilla-daemon＠bugs.koha-community.org