Hello all, I have been asked by a few developers if I would act as documentation manager for developer documentation as well as the user documentation. In order to do this I will need a committee off Developers who will 'meet' with me on a semi-regular basis to answer questions, provide feedback and even provide direction. This manual will of course be available via git and written using docbook - this means that others can help me write (in fact I encourage it). My first step is to review the wiki and pull out tips and articles and guidelines that should be in the developer manual. The idea of this document is to make it easy for new people to come in and start Koha development and to remind experienced developers of procedures that have been set in place in the past. So, if you want to help out, let me know and as always I'm open to documentation suggestions. Thanks Nicole
Hi all, I know that we're all busy, but this idea is for the best of the future of Koha - with better documentation for developers we can attract more skilled developers - and improve the work of those trying to help with development now ... so is anyone interested in being on a committee? Thanks Nicole On Mon, Mar 8, 2010 at 1:20 PM, Nicole Engard <nengard@gmail.com> wrote:
Hello all,
I have been asked by a few developers if I would act as documentation manager for developer documentation as well as the user documentation. In order to do this I will need a committee off Developers who will 'meet' with me on a semi-regular basis to answer questions, provide feedback and even provide direction.
This manual will of course be available via git and written using docbook - this means that others can help me write (in fact I encourage it). My first step is to review the wiki and pull out tips and articles and guidelines that should be in the developer manual.
The idea of this document is to make it easy for new people to come in and start Koha development and to remind experienced developers of procedures that have been set in place in the past.
So, if you want to help out, let me know and as always I'm open to documentation suggestions.
Thanks Nicole
On Thu, Mar 18, 2010 at 10:47 AM, Nicole Engard <nengard@gmail.com> wrote:
Hi all,
I know that we're all busy, but this idea is for the best of the future of Koha - with better documentation for developers we can attract more skilled developers - and improve the work of those trying to help with development now ... so is anyone interested in being on a committee?
I'll toss my hat in the ring. Kind Regards, Chris
I'll volunteer for this. Documentation is crucial, sometimes moreso than the code itself. -Ian Walls On Thu, Mar 18, 2010 at 10:57 AM, Chris Nighswonger < cnighswonger@foundations.edu> wrote:
On Thu, Mar 18, 2010 at 10:47 AM, Nicole Engard <nengard@gmail.com> wrote:
Hi all,
I know that we're all busy, but this idea is for the best of the future of Koha - with better documentation for developers we can attract more skilled developers - and improve the work of those trying to help with development now ... so is anyone interested in being on a committee?
I'll toss my hat in the ring.
Kind Regards, Chris _______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
On 18/03/10 14:47, Nicole Engard wrote:
Hi all,
I know that we're all busy, but this idea is for the best of the future of Koha - with better documentation for developers we can attract more skilled developers - and improve the work of those trying to help with development now ... so is anyone interested in being on a committee?
Yes I'll lend a hand. Colin -- Colin Campbell Chief Software Engineer, PTFS Europe Limited Content Management and Library Solutions +44 (0) 208 366 1295 (phone) +44 (0) 7759 633626 (mobile) colin.campbell@ptfs-europe.com skype: colin_campbell2 http://www.ptfs-europe.com
I'd like to help if I can. I am not a programmer per se, but would like to help make Koha more accessible. I often have questions that lead to dead ends and more questions, like my experience yesterday on the Koha IRC. My standpoint is somewhat between the developer and the librarian. I try to bring the two together. And besides, I have been wanting to contribute to the documentation effort for some time. Nelson ----- Nelson Fredsell nelsonf on Koha IRC implementing a small, non-profit union catalogue in Cape Town, South Africa -- View this message in context: http://old.nabble.com/Developer-Documentation-tp27824596p27950959.html Sent from the Koha - Dev mailing list archive at Nabble.com.
I just wanted to state that I have a developer that I am working with in house who is pretty good, but would like to better understand how all the "pieces" work together. .tmpl, .pl, inc - there are statements that refer to things that he can't find, I don't konw if that is because it is part of the C4 modules or??? TMPL_IF_NAME blah... We were looking at checkin specifically and how to put in a verification that an item was actually updated in the database. Being a newbie developer documentation is a double edge sword, but again the RM is there to help make sure the code released is high quality. Thanks for bringing it up and anyway I can help by all means let me know. David Schuster - learning along the way and discovering how much I can mess up programmers lives by dabbling. nengard wrote:
Hi all,
I know that we're all busy, but this idea is for the best of the future of Koha - with better documentation for developers we can attract more skilled developers - and improve the work of those trying to help with development now ... so is anyone interested in being on a committee?
Thanks Nicole
On Mon, Mar 8, 2010 at 1:20 PM, Nicole Engard <nengard@gmail.com> wrote:
Hello all,
I have been asked by a few developers if I would act as documentation manager for developer documentation as well as the user documentation. In order to do this I will need a committee off Developers who will 'meet' with me on a semi-regular basis to answer questions, provide feedback and even provide direction.
This manual will of course be available via git and written using docbook - this means that others can help me write (in fact I encourage it). My first step is to review the wiki and pull out tips and articles and guidelines that should be in the developer manual.
The idea of this document is to make it easy for new people to come in and start Koha development and to remind experienced developers of procedures that have been set in place in the past.
So, if you want to help out, let me know and as always I'm open to documentation suggestions.
Thanks Nicole
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
-- View this message in context: http://old.nabble.com/Developer-Documentation-tp27824596p27977027.html Sent from the Koha - Dev mailing list archive at Nabble.com.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hello all, I am building custom reports in Koha and I am having some troubles getting the right results when creating custom definitions. 1. Acquisitions by status (ordered, received, processed, new releases) 2. A detailled budget report 3. Circulation by patron categories. 4. Checked-out items by location. Can anyone help me? Regards, Claude -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEcBAEBAgAGBQJLqt1CAAoJEDbGJ8QX4NMpm/MH/0EmtrIo899yORfZefQmfr8G qz6bXUUcws7xPHKtxBcB/RI/bnktCm4Dl8qVGzP7A4vSoM7FETxXP8PyuJ2Wbcyl +JHpCBKxASus6cjDUldt7ggxj53KvMonxyAS7T+GQOKDHE+DZLGmxG89uE4D4Y68 uHbdP4bixKxxST8HEHY0RvAZs/dysZq7NIFsQFseCPNo3qnIZ3xNOmTdiaA+8Hh9 EIcOM1ApYk/Z4ztGQQZbErZ3DaYQ+lzwW/PmvsFf2VknwFF8kM67Pf6AY6CgIClP jAxgWLKNh929EO5njq+ISk9Ududq5BoyY3IPlIo5hvaI/rmuyMuDetSGb2vaL4s= =RHza -----END PGP SIGNATURE-----
Some of these types of reports can be found on the wiki: http://wiki.koha.org/doku.php?id=sql_library You can also request new reports on that page. Thanks Nicole C. Engard On Wed, Mar 24, 2010 at 11:49 PM, Claude Belizaire <claude.belizaire@sys-tech.net> wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Hello all,
I am building custom reports in Koha and I am having some troubles getting the right results when creating custom definitions.
1. Acquisitions by status (ordered, received, processed, new releases)
2. A detailled budget report
3. Circulation by patron categories.
4. Checked-out items by location.
Can anyone help me?
Regards, Claude -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iQEcBAEBAgAGBQJLqt1CAAoJEDbGJ8QX4NMpm/MH/0EmtrIo899yORfZefQmfr8G qz6bXUUcws7xPHKtxBcB/RI/bnktCm4Dl8qVGzP7A4vSoM7FETxXP8PyuJ2Wbcyl +JHpCBKxASus6cjDUldt7ggxj53KvMonxyAS7T+GQOKDHE+DZLGmxG89uE4D4Y68 uHbdP4bixKxxST8HEHY0RvAZs/dysZq7NIFsQFseCPNo3qnIZ3xNOmTdiaA+8Hh9 EIcOM1ApYk/Z4ztGQQZbErZ3DaYQ+lzwW/PmvsFf2VknwFF8kM67Pf6AY6CgIClP jAxgWLKNh929EO5njq+ISk9Ududq5BoyY3IPlIo5hvaI/rmuyMuDetSGb2vaL4s= =RHza -----END PGP SIGNATURE-----
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Thanks for the quick reply, I have looked at the link you sent. It has lots of custom queries but I would need more time then I have to complete the reports. I was able to generate a report from on of the koha demo but I would really appreciate tips help building those custom reports. I would be happy to make a donation through paypal in exchange for some help. :-) Cheers, Claude Le 2010-03-25 00:44, Nicole Engard a écrit :
Some of these types of reports can be found on the wiki: http://wiki.koha.org/doku.php?id=sql_library
You can also request new reports on that page.
Thanks Nicole C. Engard
On Wed, Mar 24, 2010 at 11:49 PM, Claude Belizaire <claude.belizaire@sys-tech.net> wrote: Hello all,
I am building custom reports in Koha and I am having some troubles getting the right results when creating custom definitions.
1. Acquisitions by status (ordered, received, processed, new releases)
2. A detailled budget report
3. Circulation by patron categories.
4. Checked-out items by location.
Can anyone help me?
Regards, Claude
Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
- -- Claude -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEbBAEBAgAGBQJLqu5dAAoJEDbGJ8QX4NMptjcH92FRU99501kjiSBoagmpj5fE 5l0g2PpeOY2X8/HXxvn/2PoYJ2btMS+A6NPcWjhQ2jxNTce98ngeHwaV0M18GuH7 WUwKySn7rYN4Iz/fAUvn+q9rd+SmdmJ9nCk4pdIKWLTLTaybI8q3arveVPhHnXX7 pNUWOCKO0zdC8WJsqLmPLb38mJljVbsgk7zAIqwa3qL/2ePrQJGdHROpkMxc9Jhx wa+6Y2ltCMYGsJjpmk4xcbUGys5ZLoqbEBqpR+Y5zmIVIRcxvMUTk3UkOd1h5Tko EAIxJv13Z3WVLkfZSfkTThZGZlB/N2j6KIoTMBKBDMn+cS+iZW5DGr/KCfG9Eg== =tBdP -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hello all, Can someone help me? I need the SQL query that would generate a report listing checked-out items by location. Cheers, Claude Le 2010-03-25 01:02, Claude Belizaire a écrit :
Thanks for the quick reply, I have looked at the link you sent. It has lots of custom queries but I would need more time then I have to complete the reports.
I was able to generate a report from on of the koha demo but I would really appreciate tips help building those custom reports.
I would be happy to make a donation through paypal in exchange for some help. :-)
Cheers, Claude
Le 2010-03-25 00:44, Nicole Engard a écrit :
Some of these types of reports can be found on the wiki: http://wiki.koha.org/doku.php?id=sql_library
You can also request new reports on that page.
Thanks Nicole C. Engard
On Wed, Mar 24, 2010 at 11:49 PM, Claude Belizaire <claude.belizaire@sys-tech.net> wrote: Hello all,
I am building custom reports in Koha and I am having some troubles getting the right results when creating custom definitions.
1. Acquisitions by status (ordered, received, processed, new releases)
2. A detailled budget report
3. Circulation by patron categories.
4. Checked-out items by location.
Can anyone help me?
Regards, Claude
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel - -- *Claude Bélizaire* Chef d`équipe Web claude.belizaire@sys-tech.net <mailto:claude.belizaire@sys-tech.net> 418 520-0739 poste 140 514 907-0036 / 1-877-969-8324 *SYS-TECH / Technologies de l'information libres* 6700 BOUL PIERRE-BERTRAND BUREAU 209 QUÉBEC QC G2J 0B4 http://www.sys-tech.net /Membre supporteur de l'Association TYPO3 <http://typo3.org>/ -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEcBAEBAgAGBQJLqvK7AAoJEDbGJ8QX4NMpfVEH/26ew/FaBHS1IN6UnKMTC4rN wy13drkkvd21esxhhg0HYg0C5pio/qgVIzxOBv9cbKolRj02Wwg1thVIycJMtvdO gm0R5Bzxr2lC1O42qiCOxAIlkOuV8Ss/0qSq/BktsebClsKSWPgFOZoIUUNk4I/n xVjPWUiboRkvGLv/B/vGftIEVBRMHchw/rlIMdgOaCARPpSv3jOoC59QLPJljuaR rCjMMtdiCU7SbBGGZkN3bQVMsCrnidBRmqODECrafIqT0C4iQF4OtuG+8DUKE9zD s1wTS0JHE7RtOJwORGsw5KLCMAPK8D2RCG0QvzbWFJCliBUrHqpal1GI6SWDoHs= =8NkZ -----END PGP SIGNATURE-----
Perhaps something like: SELECT br.branchname, b.title, b.author, it.description, i.itemcallnumber, i.barcode, c.description, p.surname, p.firstname FROM issues iss CROSS JOIN branches br USING (branchcode) CROSS JOIN items i USING (itemnumber) CROSS JOIN biblio b USING (biblionumber) CROSS JOIN itemtypes it ON i.itype = it.itemtype CROSS JOIN borrowers p USING (borrowernumber) CROSS JOIN categories c USING (categorycode) ORDER BY iss.branchcode; On Thu, 2010-03-25 at 01:20 -0400, Claude Belizaire wrote:
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Hello all,
Can someone help me? I need the SQL query that would generate a report listing checked-out items by location.
Cheers, Claude
Le 2010-03-25 01:02, Claude Belizaire a écrit :
Thanks for the quick reply, I have looked at the link you sent. It has lots of custom queries but I would need more time then I have to complete the reports.
I was able to generate a report from on of the koha demo but I would really appreciate tips help building those custom reports.
I would be happy to make a donation through paypal in exchange for some help. :-)
Cheers, Claude
Le 2010-03-25 00:44, Nicole Engard a écrit :
Some of these types of reports can be found on the wiki: http://wiki.koha.org/doku.php?id=sql_library
You can also request new reports on that page.
Thanks Nicole C. Engard
On Wed, Mar 24, 2010 at 11:49 PM, Claude Belizaire <claude.belizaire@sys-tech.net> wrote: Hello all,
I am building custom reports in Koha and I am having some troubles getting the right results when creating custom definitions.
1. Acquisitions by status (ordered, received, processed, new releases)
2. A detailled budget report
3. Circulation by patron categories.
4. Checked-out items by location.
Can anyone help me?
Regards, Claude
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
- -- *Claude Bélizaire* Chef d`équipe Web
claude.belizaire@sys-tech.net <mailto:claude.belizaire@sys-tech.net> 418 520-0739 poste 140 514 907-0036 / 1-877-969-8324
*SYS-TECH / Technologies de l'information libres* 6700 BOUL PIERRE-BERTRAND BUREAU 209 QUÉBEC QC G2J 0B4 http://www.sys-tech.net
/Membre supporteur de l'Association TYPO3 <http://typo3.org>/ -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iQEcBAEBAgAGBQJLqvK7AAoJEDbGJ8QX4NMpfVEH/26ew/FaBHS1IN6UnKMTC4rN wy13drkkvd21esxhhg0HYg0C5pio/qgVIzxOBv9cbKolRj02Wwg1thVIycJMtvdO gm0R5Bzxr2lC1O42qiCOxAIlkOuV8Ss/0qSq/BktsebClsKSWPgFOZoIUUNk4I/n xVjPWUiboRkvGLv/B/vGftIEVBRMHchw/rlIMdgOaCARPpSv3jOoC59QLPJljuaR rCjMMtdiCU7SbBGGZkN3bQVMsCrnidBRmqODECrafIqT0C4iQF4OtuG+8DUKE9zD s1wTS0JHE7RtOJwORGsw5KLCMAPK8D2RCG0QvzbWFJCliBUrHqpal1GI6SWDoHs= =8NkZ -----END PGP SIGNATURE-----
_______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
-- Michael Hafen Systems Analyst and Programmer Washington County School District Utah, USA for Koha checkout http://development.washk12.org/gitweb/ or git://development.washk12.org/koha
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 I was asked a question regarding notices that I have trouble understanding. How many notices (Dewey, LCC, etc.) are available per class? Can someone help me figure out what this means and what the appropriate answer would be? Cheers, Claude -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (MingW32) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEcBAEBAgAGBQJLq6cpAAoJEDbGJ8QX4NMpTHMIAL3K3UuUBbHdCQ5ea4Ily6O/ UrVsFwtCd1N96bBFfNxkxH2UdZbnJMLPzMNK15eKqtlwomlylybMyHO4+f6v8epG IbM4Bks2GPZMOfquaRS8o9OmM9uzf1CJmheu4t3Qp5RMZfSpppO/KtoSnhGkLX6w 4zB5h+2hfhaNmP7lmzH+uZBt72He0pGNzmGoUBd9AJ5L3ebxtFkqvM6VtvqiETK1 3csMovzJWEBSK0pqBWNfad4/7SQM/Qrs9wPFTB/6zYQxTxv/lbkn6wYtFU52wJbB CAIVOdxA3/bjgZFZnU927qx4d04eNc2oU+GuGrM7AV8IVVr0KZemZzEjb3am0Ms= =mGBd -----END PGP SIGNATURE-----
Hi, On Mon, Mar 8, 2010 at 1:20 PM, Nicole Engard <nengard@gmail.com> wrote:
This manual will of course be available via git and written using docbook - this means that others can help me write (in fact I encourage it). My first step is to review the wiki and pull out tips and articles and guidelines that should be in the developer manual.
Developer documentation is a good thing, but I don't think that a DocBook document is necessarily the best way to present it - it does not encourage on-the-fly updates, and the idea of a Koha developer documentation committee that acts as an implicit gatekeeper bothers me. I think more active maintenance of the developer sections on the wiki would be a better approach, possibly in conjunction with a bit of work to allow it to be exported as DocBook for those who prefer to consume it that way. Regards, Galen -- Galen Charlton gmcharlt@gmail.com
On Thu, Mar 18, 2010 at 11:15 AM, Galen Charlton <gmcharlt@gmail.com> wrote:
Developer documentation is a good thing, but I don't think that a DocBook document is necessarily the best way to present it - it does not encourage on-the-fly updates, and the idea of a Koha developer documentation committee that acts as an implicit gatekeeper bothers me. I think more active maintenance of the developer sections on the wiki would be a better approach, possibly in conjunction with a bit of work to allow it to be exported as DocBook for those who prefer to consume it that way.
The wiki is not organized - it's way too hard to navigate for someone who is not familiar with is and adding more links is not going to help - in my opinion - and the point is to make it easy for those who are not familiar with the code or coding for Koha. If DocBook is not the answer, then I'm up for suggestions of structured ways to provide new developers with a guide of where to start, what to do and not do... I've been a member of the community for 3+ years - not that long in the grand scheme of things, but long enough that I should know more about development guidelines than I do and that's simply because I will not sit and skim the entire wiki to find what I'm looking for ... Nicole
Hi, On Thu, Mar 18, 2010 at 11:43 AM, Nicole Engard <nengard@gmail.com> wrote:
The wiki is not organized - it's way too hard to navigate for someone who is not familiar with is and adding more links is not going to help - in my opinion - and the point is to make it easy for those who are not familiar with the code or coding for Koha.
Absolutely nothing precludes rewriting content on the wiki or reorganizing it. Once the new wiki is up, we'll have an opportunity to start with a clean slate anyway.
If DocBook is not the answer, then I'm up for suggestions of structured ways to provide new developers with a guide of where to start, what to do and not do... I've been a member of the community for 3+ years - not that long in the grand scheme of things, but long enough that I should know more about development guidelines than I do and that's simply because I will not sit and skim the entire wiki to find what I'm looking for ...
And not all people interested in development will read a manual. :) Some will, of course, but ultimately, we'll have to be sensitive to the fact that there will be a lot of paths for people to become Koha developers. In any event, my strong preference is to promote a method for developer documentation that encourages *direct* updates by the developers. Regards, Galen -- Galen Charlton gmcharlt@gmail.com
On Thu, Mar 18, 2010 at 11:55 AM, Galen Charlton <gmcharlt@gmail.com> wrote:
And not all people interested in development will read a manual. :) Some will, of course, but ultimately, we'll have to be sensitive to the fact that there will be a lot of paths for people to become Koha developers. In any event, my strong preference is to promote a method for developer documentation that encourages *direct* updates by the developers.
And that is my plan as well :) To have developers be able to edit the documentation at any time - which can be done by putting the XML file up in a public git repo - just like Koha. But I'm up for suggestions from all - like I said this was a project I was asked to do by only a few developers - and I'm happy that now I have some public feedback going on :) Nicole
On 19 March 2010 04:59, Nicole Engard <nengard@gmail.com> wrote:
On Thu, Mar 18, 2010 at 11:55 AM, Galen Charlton <gmcharlt@gmail.com> wrote:
And not all people interested in development will read a manual. :) Some will, of course, but ultimately, we'll have to be sensitive to the fact that there will be a lot of paths for people to become Koha developers. In any event, my strong preference is to promote a method for developer documentation that encourages *direct* updates by the developers.
And that is my plan as well :) To have developers be able to edit the documentation at any time - which can be done by putting the XML file up in a public git repo - just like Koha. But I'm up for suggestions from all - like I said this was a project I was asked to do by only a few developers - and I'm happy that now I have some public feedback going on :)
I have to agree with Galen on this. Documentation is excellent, committees aren't :) I think a well structured section of the wiki would be my preference. Are you allowed to say who asked for the developer docs? Chris
It's a thorny problem, there are several distinct classes of documentation and each are least worst served by different schemes. - style guides and other "how to do business" -- something formal but easy to edit like a well sorted wiki section with a designated caretaker to keep it nice - designs that are under discussion -- wiki pages under a section devoted to that activity - designs that are ratified -- something tamper resistant like a pdf (from docbook or ODT sources) - implementation details -- POD, inline docs made by the developer; release manager would review and could reject if missing I've never seen it done well if that helps. -reed
Hi Reed As we want to bridge the gap between developers and users and assist users to become (or engage more with) developers and developers to become better users, is it wise to repeat something you say "I've never seen it done well"? My suggestion is that one adds to the 4 categories of developer documentation you list, 2 important documents: the "User Guide" and "Client Requirements Guide" to frame a more complete picture. Just like adjusting the size of the font to suit our visual needs when reading web pages, if the reader could adjust the documentation reading level to suit their information needs by clicking on the - or + signs like when viewing Google maps .... that would be cool! Then we truly would document requirements and knowledge from the library patron, the library staff and the amazing Koha developers all in one multi layered manual. Cheers, Irma CALYX -----Original Message----- From: koha-devel-bounces@lists.koha.org [mailto:koha-devel-bounces@lists.koha.org] On Behalf Of Reed Wade Sent: Friday, 19 March 2010 7:32 AM To: Koha Devel Subject: Re: [Koha-devel] Developer Documentation It's a thorny problem, there are several distinct classes of documentation and each are least worst served by different schemes. - style guides and other "how to do business" -- something formal but easy to edit like a well sorted wiki section with a designated caretaker to keep it nice - designs that are under discussion -- wiki pages under a section devoted to that activity - designs that are ratified -- something tamper resistant like a pdf (from docbook or ODT sources) - implementation details -- POD, inline docs made by the developer; release manager would review and could reject if missing I've never seen it done well if that helps. -reed _______________________________________________ Koha-devel mailing list Koha-devel@lists.koha.org http://lists.koha.org/mailman/listinfo/koha-devel
On 19 March 2010 11:44, Irma Birchall <irma@calyx.net.au> wrote:
Hi Reed
As we want to bridge the gap between developers and users and assist users to become (or engage more with) developers and developers to become better users, is it wise to repeat something you say "I've never seen it done well"?
What Reed meant, is he has never seen developer documentation done well. Which I have to agree with him I haven't either, this isn't to say not to try just that it is a hard problem to solve.
My suggestion is that one adds to the 4 categories of developer documentation you list, 2 important documents: the "User Guide" and "Client Requirements Guide" to frame a more complete picture.
Just like adjusting the size of the font to suit our visual needs when reading web pages, if the reader could adjust the documentation reading level to suit their information needs by clicking on the - or + signs like when viewing Google maps .... that would be cool!
Then we truly would document requirements and knowledge from the library patron, the library staff and the amazing Koha developers all in one multi layered manual.
Yep, that's the easy bit, getting developers to write it is the trick. Lars had a suggestion and I agree to quote him "ideally I would see the dev docs in the source tree, and a culture of updating them whenever the code changes" It's building that culture that is the tricky bit. Dev changes so fast that we need to make sure the doc changes with it, having it in the same place as the code and having an expectation that patches that change code, change the doc too seems like one of the few ways to make it happen. Chris
On Fri, 2010-03-19 at 11:51 +1300, Chris Cormack wrote:
It's building that culture that is the tricky bit. Dev changes so fast that we need to make sure the doc changes with it, having it in the same place as the code and having an expectation that patches that change code, change the doc too seems like one of the few ways to make it happen.
I suspect that it would be crucial for the release manager, or whoever accepts patches into the main development branch, enforce this. After a while, it should become second nature to all frequent developers. Obviously there will be situations in which someone may be able to fix a bug, but not understand enough to update the documentation, too. In that case, posting a preliminary patch to koha-devel asking for help would seem to be the best way to handle this.
On Thu, Mar 18, 2010 at 6:51 PM, Chris Cormack <chris@bigballofwax.co.nz> wrote:
Yep, that's the easy bit, getting developers to write it is the trick.
That's what I was trying to do - to do the writing for the developers based on info I gathered by talking to them ... the problem with developer written documentation is that it does not instill a sense of understanding or comfort in non-developers who want to try and learn - hence having a librarian write a guide for those newbie developers. Nicole
On 20 March 2010 01:11, Nicole Engard <nengard@gmail.com> wrote:
On Thu, Mar 18, 2010 at 6:51 PM, Chris Cormack <chris@bigballofwax.co.nz> wrote:
Yep, that's the easy bit, getting developers to write it is the trick.
That's what I was trying to do - to do the writing for the developers based on info I gathered by talking to them ... the problem with developer written documentation is that it does not instill a sense of understanding or comfort in non-developers who want to try and learn - hence having a librarian write a guide for those newbie developers.
Ohhh so a newbie guide is what you are planning? That is something that could stand alone, but I think the actual code documentation needs to live with the code. Chris
I'm looking for a guide for those new to programming for Koha - rules on how to participate, rules on what to do and not do, rules on where to start - so a newbie guide to jumping into Koha as a developer. Nicole On Fri, Mar 19, 2010 at 4:03 PM, Chris Cormack <chris@bigballofwax.co.nz> wrote:
On 20 March 2010 01:11, Nicole Engard <nengard@gmail.com> wrote:
On Thu, Mar 18, 2010 at 6:51 PM, Chris Cormack <chris@bigballofwax.co.nz> wrote:
Yep, that's the easy bit, getting developers to write it is the trick.
That's what I was trying to do - to do the writing for the developers based on info I gathered by talking to them ... the problem with developer written documentation is that it does not instill a sense of understanding or comfort in non-developers who want to try and learn - hence having a librarian write a guide for those newbie developers.
Ohhh so a newbie guide is what you are planning? That is something that could stand alone, but I think the actual code documentation needs to live with the code.
Chris
On 20 March 2010 11:43, Nicole Engard <nengard@gmail.com> wrote:
I'm looking for a guide for those new to programming for Koha - rules on how to participate, rules on what to do and not do, rules on where to start - so a newbie guide to jumping into Koha as a developer.
If you substitute the world guideline for rules, I'd be much happier. We don't have rules, we have guidelines. Chris
On Sat, Mar 20, 2010 at 11:43 AM, Nicole Engard <nengard@gmail.com> wrote:
I'm looking for a guide for those new to programming for Koha - rules on how to participate, rules on what to do and not do, rules on where to start - so a newbie guide to jumping into Koha as a developer.
Nicole
Ah! Sorry, I missed what it was you're actually doing. I have seen that done well. The first example that comes to mind is about 10 wiki pages together in a set. They are titled things like "Getting Started" that steps you through getting your dev environment set up through to a running system. Also, "Git Cheat Sheet" and "Coding Style Guide". The set I'm thinking of is exactly what we point new developers at inside our team at Catalyst (and which primarily relate to a non-koha project). But, it's also the reference guides for not so new developers. That keeps it current but still mostly correct and complete. I'd suggest using the wiki for sure. The current one needs a strong tidy up. -reed
On Fri, Mar 19, 2010 at 11:44 AM, Irma Birchall <irma@calyx.net.au> wrote:
Hi Reed
As we want to bridge the gap between developers and users and assist users to become (or engage more with) developers and developers to become better users, is it wise to repeat something you say "I've never seen it done well"?
Chris correctly interpreted for me -- it's more a general "I've never seen a really satisfying and working scheme but here's something that might could work if we are diligent."
My suggestion is that one adds to the 4 categories of developer documentation you list, 2 important documents: the "User Guide" and "Client Requirements Guide" to frame a more complete picture.
Just like adjusting the size of the font to suit our visual needs when reading web pages, if the reader could adjust the documentation reading level to suit their information needs by clicking on the - or + signs like when viewing Google maps .... that would be cool!
Then we truly would document requirements and knowledge from the library patron, the library staff and the amazing Koha developers all in one multi layered manual.
That would be pretty sweet. One path which might lead us there could be tagging. I do not think a central document stands a good chance of staying correct and current. But, I can certainly imagine feature tags that could be applied so that a view extracted from the various sources (wiki, code comments, bugzilla, etc) could be displayed together. -reed
Of course I can :) It was Nicolas at BibLibre - and maybe some others over there. Also it was something I asked for first ;) so I could find documentation on how to participate and it was suggested that as doc manager I could work on that - but I can't do it alone cause I don't know the rules :) -- catch 22. Nicole On Thu, Mar 18, 2010 at 4:08 PM, Chris Cormack <chris@bigballofwax.co.nz> wrote:
On 19 March 2010 04:59, Nicole Engard <nengard@gmail.com> wrote:
On Thu, Mar 18, 2010 at 11:55 AM, Galen Charlton <gmcharlt@gmail.com> wrote:
And not all people interested in development will read a manual. :) Some will, of course, but ultimately, we'll have to be sensitive to the fact that there will be a lot of paths for people to become Koha developers. In any event, my strong preference is to promote a method for developer documentation that encourages *direct* updates by the developers.
And that is my plan as well :) To have developers be able to edit the documentation at any time - which can be done by putting the XML file up in a public git repo - just like Koha. But I'm up for suggestions from all - like I said this was a project I was asked to do by only a few developers - and I'm happy that now I have some public feedback going on :)
I have to agree with Galen on this. Documentation is excellent, committees aren't :) I think a well structured section of the wiki would be my preference. Are you allowed to say who asked for the developer docs?
Chris
participants (13)
-
Chris Cormack -
Chris Nighswonger -
Claude Belizaire -
Colin Campbell -
David Schuster -
Galen Charlton -
Ian Walls -
Irma Birchall -
Lars Wirzenius -
Michael Hafen -
Nelson Fredsell -
Nicole Engard -
Reed Wade