What documentiondto we want, were do we put it and how do we maintain it [Was: Re: [Trac] Re: Trac Recipies]
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 [Snip Cookbook def - it's a collection of Howto's/recipes] Noah Kantrowitz skrev 04. juni 2009 20:01: What you describe _is_ documentation. It belongs with the rest of the documentation. If you would like to contribute such docs, we would welcome it. Just type them up and put them on the wiki or in a ticket. After reading this thread, and the older trac-dev sphinx thread, as well as looking at the latest t.e.o wiki -- I'm actually still confused as to what documentation should go where, how to best contribute, and how to balance tickets vs wiki vs documentation sourcecode (in the repo). I think we need to rethink (or document plainly on the wiki) the terms trac user and trac developer. trac end user and trac contributor might be better labels, a contributor being anyone that submits code (python, javascript, html and templates) or documentation (wiki, newhelp) changes. This so that the many knowledgeable trac users can help with translating, extending and end user proofing the documentation. This may be as easy as making sure that there is a natural and direct path from the t.e.o front page to the various dev-guides *also* for those wanting to write a howto, proof-read or translate documentation. We need to remember that not everyone will equate document trac-admin in Norwegian with how do I check in my python patches to trac-core. I think the developers' hearts are in the right place, but we might have a bit of a culture gap between core devs and the growing group of trac users. I tried to put myself in the mind of a trac user with little or no interest/knowledge of coding, and came up with a couple of simple use-cases: A Trac user/contributor might want to: 1) Correct spelling errors in existing documentation 2) Update a documentation section to reflect new behaviour after a new release (eg: 0.10 - 0.11) 3) Translate a documentation section to Japanese or Norwegian 4) Write a short hand-holding end-user-proof HOWTO on setting up trac for windows 7 with plugins a b and c, for workflow X, with users in AD. The workflow should(?) then be: * search to see if a ticket exists - if not: Make ticket (eg: spelling errors OR request for translation) * Check out documentation tree (trunk/doc in rst/sphinx format ?) * Update relevant section (eg: fix spelling errors, branch-and-translate-to Japanese) * Generate patch * attach patch to ticket * A developer commits patch, public documentation updated, ticket closed (This is http://trac.edgewall.org/wiki/HowToContribute + http://trac.edgewall.org/wiki/TracDev/SubmittingPatches ) Or: to 4) create a new howto on installing trac on windows 7: * search to see if a ticket exists - if not make one * (Write the text, take the screenshots) * Make a page on the wiki, attach screenshots * link from ticket to page/doc * Someone (tm) sanitychecks, converts to rst, updates repo ? What would be the best approach to 3) Translate a documentation section to Japanese ? Where would that documentation go ? Or a Norwegian translation ? I guess the workflow for any Trac stuff should be: 1: Search wiki/bug db 2: Make/update ticket 3: Solve ticket (ie: apply patch) This is more-or-less how things work now ? Is this about right / how the devs want it ? What do we actually want to have in the wiki vs newhelp ? Should we have /trunk/doc/contrib/howto|coobook etc ? I found: http://trac.edgewall.org/wiki/TranslationRu/TracAdmin, does this mean that case 4) would involve creating /TranslationJp/xx ? Maybe we need a short summary like the workflow above, on the trac front page or on the How to contribute page ? It's not that it's a great evil to have trac howtos on personal blogs, other wikis, and other documentation sites -- but I believe we should allow those willing to help, to have a clear and easy path to do so. I know I personally quickly abandon all hope of donating free work to projects, if I must spend half a day figuring out how to submit my changes. I don't usually need to do that any more, as I'm aware most developers love patches, and hate just about everything else -- but those seeing Trac as a project management tool and a wiki need a quick up-front hint on how to proceed. See also my *other* thread hijack regarding ReST vs Trac wiki markup. - -e - -- .---. Eirik Schwenke eirik.schwe...@nsd.uib.no ( NSD ) Harald Hårfagresgate 29Rom 150 '---' N-5007 Bergentlf: (555) 889 13 GPG-key at pgp.mit.edu Id 0x8AA3392C -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkooG3QACgkQxUW7FIqjOSzRDQCgzPF1jWPSVSb4zbhkpw73uSdi EXAAoMvesdTeGcpjgPRBqVNxvZR3fqnA =rI1f -END PGP SIGNATURE- --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users
Re: What documentiondto we want, were do we put it and how do we maintain it [Was: Re: [Trac] Re: Trac Recipies]
Well, I want two tons of docs and an special edition containing all my Tracky poems covered by the finest cheeze ever made (include zome cheezburgerz pleaze ;), I want them to be inside a box, I want you to put me inside that box too, and maintain it closed ... until my triumph be announced in Trac-land. XD On Thu, Jun 4, 2009 at 2:07 PM, Eirik Schwenke eirik.schwe...@nsd.uib.no wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 [Snip Cookbook def - it's a collection of Howto's/recipes] Noah Kantrowitz skrev 04. juni 2009 20:01: What you describe _is_ documentation. It belongs with the rest of the documentation. If you would like to contribute such docs, we would welcome it. Just type them up and put them on the wiki or in a ticket. After reading this thread, and the older trac-dev sphinx thread, as well as looking at the latest t.e.o wiki -- I'm actually still confused as to what documentation should go where, how to best contribute, and how to balance tickets vs wiki vs documentation sourcecode (in the repo). Well it seems it's more complex than I though. I think we need to rethink (or document plainly on the wiki) the terms trac user and trac developer. trac end user and trac contributor might be better labels, a contributor being anyone that submits code (python, javascript, html and templates) or documentation (wiki, newhelp) changes. Let me see if I get the idea : - Contributor : a contributor being anyone that submits code (python, javascript, html and templates) or documentation (wiki, newhelp) changes. (This one seems to be ok for me) - Trac developer : What's the difference between a Trac dev and a contributor that submits code ( checkin permissions ?) - trac user : ¿? - trac end user: ¿? What's the difference Look, two hints (I dont know if somebody has mentionned this before) : - Roles should be determined considering the different user profiles (e.g. Trac admin (and | or) Server admin, plugin dev, core dev, Trac user, ...) - I forgot the second. I'm getting old damn it ! grgrggrggrggr - There should be a reference, a user guide, and a cookbook (perhaps this ìs obvious but anyway) - Participation should be more open (e.g. plugin ownership) all this is IMHO and I'm not a Trac dev ;) A Trac user/contributor might want to: 1) Correct spelling errors in existing documentation 2) Update a documentation section to reflect new behaviour after a new release (eg: 0.10 - 0.11) 3) Translate a documentation section to Japanese or Norwegian 4) Write a short hand-holding end-user-proof HOWTO on setting up trac for windows 7 with plugins a b and c, for workflow X, with users in AD. And something similar happens with plugins in isolation. I found: http://trac.edgewall.org/wiki/TranslationRu/TracAdmin, does this mean that case 4) would involve creating /TranslationJp/xx ? What about using Wiki Negotiation plugin ? Maybe we need a short summary like the workflow above, on the trac front page or on the How to contribute page ? It's not that it's a great evil to have trac howtos on personal blogs, other wikis, and other documentation sites -- but I believe we should allow those willing to help, to have a clear and easy path to do so. and I also believe that is far more easy to have everything in a single place and not being lost in a mountain of search results in order to config Apache + Trac + SVN with Active Directory for instance I know I personally quickly abandon all hope of donating free work to projects, if I must spend half a day figuring out how to submit my changes. Oh ! yes ... -- Regards, Olemis. Blog ES: http://simelo-es.blogspot.com/ Blog EN: http://simelo-en.blogspot.com/ Featured article: PyUMLGraph : Otra manera de contemplar el código - http://feedproxy.google.com/~r/simelo-es/~3/lLsxDz4Rkgc/pyumlgraph-mirando-al-codigo-de-python.html --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Trac Users group. To post to this group, send email to trac-users@googlegroups.com To unsubscribe from this group, send email to trac-users+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~--~~~~--~~--~--~---
