Notices and slips documentation RFC
Koha doesn't currently have a single point of truth for documentation of notices and slips, which has lead to a proliferation of markup syntaxes, especially in regard to repeating detail, e.g. DUEDGST/PREDUEDGST: <<items.content>> ODUE* <<items.content>> or <item> </item> CHECKOUT/CHECKIN/RENEWAL ---- Detail here ---- These have been documented in https://wiki.koha-community.org/wiki/Customising_Notices_and_Slips#Notice_Ma... , but this has gotten out of date as new notices get added in each version of Koha. Work to be done: Add Koha/Notices.pod which will document the following for each notice in the Letter table: * Letter Code * Source file where the notice is populated * Logic that triggers the notice * Detail syntax (if any) * Available data (tables and substitutions) * Message transport restrictions The output from this pod should be used as the basis for the Koha user documentation. See Bug 21858 and https://wiki.koha-community.org/wiki/Notice_documentation_rfc
Until 17.11, there was a Field Guide for Notices and slips in Koha documentation (https://koha-community.org/manual/17.11/en/html/17_miscellaneous.html#field-...) but it seems to have desappeared in 18.05 Regards S. Meynieux -- Responsable support BibLibre + 33 (0)4 91 81 35 08 http://www.biblibre.com Le 19/11/2018 à 02:23, Barton Chittenden a écrit :
Koha doesn't currently have a single point of truth for documentation of notices and slips, which has lead to a proliferation of markup syntaxes, especially in regard to repeating detail, e.g.
DUEDGST/PREDUEDGST:
<<items.content>>
ODUE*
<<items.content>> or <item> </item>
CHECKOUT/CHECKIN/RENEWAL ---- Detail here ----
These have been documented in https://wiki.koha-community.org/wiki/Customising_Notices_and_Slips#Notice_Ma... , but this has gotten out of date as new notices get added in each version of Koha.
Work to be done:
Add Koha/Notices.pod which will document the following for each notice in the Letter table:
* Letter Code * Source file where the notice is populated * Logic that triggers the notice * Detail syntax (if any) * Available data (tables and substitutions) * Message transport restrictions
The output from this pod should be used as the basis for the Koha user documentation.
See Bug 21858 and https://wiki.koha-community.org/wiki/Notice_documentation_rfc
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
Hi Sophie
Until 17.11, there was a Field Guide for Notices and slips in Koha documentation
(https://koha-community.org/manual/17.11/en/html/17_miscellaneous.html#field-...)
but it seems to have desappeared in 18.05
For Koha 18.05 you can find the field guide at https://koha-community.org/manual/18.05/en/html/17_miscellaneous.html#field-... Best wishes: Michael -- Geschäftsführer · Diplombibliothekar BBS, Informatiker eidg. Fachausweis Admin Kuhn GmbH · Pappelstrasse 20 · 4123 Allschwil · Schweiz T 0041 (0)61 261 55 61 · E mik@adminkuhn.ch · W www.adminkuhn.ch
Thanks, It's ok with the url but you can't find it (or I can't find it) directly on 18.05 documentation page Sophie -- Responsable support BibLibre + 33 (0)4 91 81 35 08 http://www.biblibre.com Le 19/11/2018 à 14:44, Michael Kuhn a écrit :
Hi Sophie
Until 17.11, there was a Field Guide for Notices and slips in Koha documentation
(https://koha-community.org/manual/17.11/en/html/17_miscellaneous.html#field-...)
but it seems to have desappeared in 18.05
For Koha 18.05 you can find the field guide at
https://koha-community.org/manual/18.05/en/html/17_miscellaneous.html#field-...
Best wishes: Michael
The field guide is based on the wiki page, which I maintained... but I think that developers should be documenting any notices they add, which is why I've added this to the agenda for Wednesday's dev meeting: *Review of coding guidelines* - Proposed coding guideline DOC2: Entries in the *letter* table must be documented in *Koha/Notices.pod*. See Bug 21858 - RFC: Notices and slips documentation <https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=21858> On Mon, Nov 19, 2018 at 8:55 AM Sophie Meynieux < sophie.meynieux@biblibre.com> wrote:
Thanks, It's ok with the url but you can't find it (or I can't find it) directly on 18.05 documentation page
Sophie
-- Responsable support BibLibre + 33 (0)4 91 81 35 08 http://www.biblibre.com
Le 19/11/2018 à 14:44, Michael Kuhn a écrit :
Hi Sophie
Until 17.11, there was a Field Guide for Notices and slips in Koha documentation
( https://koha-community.org/manual/17.11/en/html/17_miscellaneous.html#field-...)
but it seems to have desappeared in 18.05
For Koha 18.05 you can find the field guide at
https://koha-community.org/manual/18.05/en/html/17_miscellaneous.html#field-...
Best wishes: Michael
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
I agree with Katrin here, I have been slowly working manual submissions into my QA workflow with requests for patch authors to submit a corresponding manual submission at the same time as the Bugzilla entry. Documenting notices feels like it fits in nicely with that.. rather than requiring double work (POD + Manual) we should be requiring just one place be updated. I'd have no issues with adding a specific coding guideline for this sort of thing however.. right now I just encourage corresponding manual merge requests but I can't really Fail QA on a patch that doesn't have one. *Martin Renvoize* <https://www.ptfs-europe.com> Development Team Manager *Phone:* +44 (0) 1483 378728 *Mobile:* +44 (0) 7725 985 636 *Email:* martin.renvoize@ptfs-europe.com *Fax:* +44 (0) 800 756 6384 www.ptfs-europe.com Registered in the United Kingdom No. 06416372 VAT Reg No. 925 7211 30 The information contained in this email message may be privileged, confidential and protected from disclosure. If you are not the intended recipient, any dissemination, distribution or copying is strictly prohibited. If you think that you have received this email message in error, please email the sender at info@ptfs-europe.com On Mon, 19 Nov 2018 at 15:22, Katrin Fischer <Katrin.Fischer.83@web.de> wrote:
Hi,
I feel if we want one source of truth besides the source code, it would make sense to submit patches to the manual directly instead of adding more documentation outside of it. Adding a POD file will need another person to work on adding it to the manual regularly. Let's not make things more complicated!
Katrin
*Gesendet:* Montag, 19. November 2018 um 16:15 Uhr *Von:* "Barton Chittenden" <barton@bywatersolutions.com> *An:* sophie.meynieux@biblibre.com *Cc:* Koha-devel <koha-devel@lists.koha-community.org> *Betreff:* Re: [Koha-devel] Notices and slips documentation RFC The field guide is based on the wiki page, which I maintained... but I think that developers should be documenting any notices they add, which is why I've added this to the agenda for Wednesday's dev meeting:
*Review of coding guidelines*
- Proposed coding guideline DOC2: Entries in the *letter* table must be documented in *Koha/Notices.pod*. See Bug 21858 - RFC: Notices and slips documentation <https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=21858>
On Mon, Nov 19, 2018 at 8:55 AM Sophie Meynieux < sophie.meynieux@biblibre.com> wrote:
Thanks, It's ok with the url but you can't find it (or I can't find it) directly on 18.05 documentation page
Sophie
-- Responsable support BibLibre + 33 (0)4 91 81 35 08 http://www.biblibre.com
Le 19/11/2018 à 14:44, Michael Kuhn a écrit :
Hi Sophie
Until 17.11, there was a Field Guide for Notices and slips in Koha documentation
( https://koha-community.org/manual/17.11/en/html/17_miscellaneous.html#field-... )
but it seems to have desappeared in 18.05
For Koha 18.05 you can find the field guide at
https://koha-community.org/manual/18.05/en/html/17_miscellaneous.html#field-...
Best wishes: Michael
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/ _______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
I see your point about eliminating duplication of effort... somewhat less so about failing QA for lack of documentation... undocumented features become a support issue, and that falls in my lap ;-). --Barton On Mon, Nov 19, 2018 at 10:30 AM Renvoize, Martin < martin.renvoize@ptfs-europe.com> wrote:
I agree with Katrin here, I have been slowly working manual submissions into my QA workflow with requests for patch authors to submit a corresponding manual submission at the same time as the Bugzilla entry.
Documenting notices feels like it fits in nicely with that.. rather than requiring double work (POD + Manual) we should be requiring just one place be updated.
I'd have no issues with adding a specific coding guideline for this sort of thing however.. right now I just encourage corresponding manual merge requests but I can't really Fail QA on a patch that doesn't have one.
*Martin Renvoize*
Development Team Manager
*Phone:* +44 (0) 1483 378728
*Mobile:* +44 (0) 7725 985 636
*Email:* martin.renvoize@ptfs-europe.com
*Fax:* +44 (0) 800 756 6384
www.ptfs-europe.com
Registered in the United Kingdom No. 06416372 VAT Reg No. 925 7211 30
The information contained in this email message may be privileged, confidential and protected from disclosure. If you are not the intended recipient, any dissemination, distribution or copying is strictly prohibited. If you think that you have received this email message in error, please email the sender at info@ptfs-europe.com
On Mon, 19 Nov 2018 at 15:22, Katrin Fischer <Katrin.Fischer.83@web.de> wrote:
Hi,
I feel if we want one source of truth besides the source code, it would make sense to submit patches to the manual directly instead of adding more documentation outside of it. Adding a POD file will need another person to work on adding it to the manual regularly. Let's not make things more complicated!
Katrin
*Gesendet:* Montag, 19. November 2018 um 16:15 Uhr *Von:* "Barton Chittenden" <barton@bywatersolutions.com> *An:* sophie.meynieux@biblibre.com *Cc:* Koha-devel <koha-devel@lists.koha-community.org> *Betreff:* Re: [Koha-devel] Notices and slips documentation RFC The field guide is based on the wiki page, which I maintained... but I think that developers should be documenting any notices they add, which is why I've added this to the agenda for Wednesday's dev meeting:
*Review of coding guidelines*
- Proposed coding guideline DOC2: Entries in the *letter* table must be documented in *Koha/Notices.pod*. See Bug 21858 - RFC: Notices and slips documentation <https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=21858>
On Mon, Nov 19, 2018 at 8:55 AM Sophie Meynieux < sophie.meynieux@biblibre.com> wrote:
Thanks, It's ok with the url but you can't find it (or I can't find it) directly on 18.05 documentation page
Sophie
-- Responsable support BibLibre + 33 (0)4 91 81 35 08 http://www.biblibre.com
Le 19/11/2018 à 14:44, Michael Kuhn a écrit :
Hi Sophie
Until 17.11, there was a Field Guide for Notices and slips in Koha documentation
( https://koha-community.org/manual/17.11/en/html/17_miscellaneous.html#field-... )
but it seems to have desappeared in 18.05
For Koha 18.05 you can find the field guide at
https://koha-community.org/manual/18.05/en/html/17_miscellaneous.html#field-...
Best wishes: Michael
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/ _______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha-community.org http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel website : http://www.koha-community.org/ git : http://git.koha-community.org/ bugs : http://bugs.koha-community.org/
participants (5)
-
Barton Chittenden -
Katrin Fischer -
Michael Kuhn -
Renvoize, Martin -
Sophie Meynieux