Use the source Luke -- what could be done to help documentation process? Request for comments!
A while a ago there was discussion about the community stalling and the state of the documentation. As far as I can remember and see, there wasn't really any agreements or solutions what to do -- so I raise the question again -- and propably aim it to the people at Zope corp., what we -- noble users -- could do to help your work on documentation? I am no frigging genius, but after banging my head enough to the wall I learned to turn into the source code and find answers from there. As it brings some enligthment from time to time, I - personally - would like to help others to find the answers more easily, and possibly let them solve some other problem and that way help me, while I'm propably facing that problem in the future. We have a great community -- that is unfortunately in very many pieces around the world. Nice thing is the diversity, but in some cases the effiency suffers. Should one turn into ZDP, Zope zen, zope newbies, zopelabs or search through the mailinglists? Huh? Joel Burton asked wether there would be people interested to help in these efforts, or more precise to be leaders in such cases. I emailed him that I would like to help, but at this stage could not be a leader of any kind. Now I am asking, is there -- in the wide open world -- a person or persons, who would like to help the community get back on the knowledge building-track? What I am suggesting is that together we create a certain set of methods of work, that we all will follow and help others to follow. These will include some etiquette on the mailinglists, howto's and what to do with the information -- for example where to store good code snipplets etc. I know it sounds hard and would require work with many people, especially the great persons who now maintain great sites at zope.org -- but also zopezen.oeg, zopelabs.com, zopenewbies etc. We have so much what we could - for example tell stories and write case scenarios about how we have used Zope and how we have planned to use it in future. There is whole lot of tacit knowledge stored into many of the seasoned Zope-developers and the challenge for the whole community is to get that knowledge into usable form. While Dieter's and others replies on the mailing lists are excellent, I believe that we could achieve more. For example by writing summaries of our problems and solutions, and storing them in some good format with good metadata so that the searches will find them better than now. But where and how? This is where we - as a community - would need to make decisions and stick by them. Possibly it would require that some persons would work as a coordinators, and many others -- just like myself -- would assist them by creating content and moving information from one place to another. But coordination is the key, wether you like it or not. It only requires some time and commitment -- which for most of us equals money. But count the numbers and tell me honestly, would you have any less -- or way much more, if our community for some parts would work like a well oiled machine. Atleast for me, Zope has been a great source of inspiration -- and honestly changed the way I see development... And I would be honoured to give something really valuable back. That was my 0.5 euros from Finland ,-) -huima
A while a ago there was discussion about the community stalling and the state of the documentation. As far as I can remember and see, there wasn't really any agreements or solutions what to do -- so I raise the question again -- and propably aim it to the people at Zope corp., what we -- noble users -- could do to help your work on documentation?
(FWIW, as of today, I am at least nominally in charge of documentation at Zope Corporation.) At the moment, I am concentrating on improving the state of the canonical "booklike" docs (the Developer's Guide and the Zope Book). Since it's a part-time job (I'm also doing customer work), it's going to go pretty slowly. But it is going. I'd love some feedback on what I'm doing and what I plan on doing. Here's what I've done so far: - Improved the BackTalk documentation system (a system for displaying and allowing comment on booklike content) to do simple things like accept multiline comments and not break when someone comments on a (preformatted) example paragraph. See it at http://www.zope.org/Documentation/ZDG Here's what I'm working on at the moment: - Enable automatic PDF generation from booklike sets of structured text documents (ala the Zope Book). This will help form the basis for a new "canonical" documentation workflow that gets CVS out of the loop. - Make the "canonical" place for the Zope Book a BackTalk book in order to allow easy commentability. Currently the Zope Book only allows comments via a SourceForge tracker. The "canonical" version of the Zope Book is currently kept in CVS, which is not readily commentable by the average reader. - Develop a system for producing "release" documentation at each Zope release. The release documentation will be immutable and downloadable in PDF and HTML. For example, there will likely be PDFs and HTML tarballs of the DevGuide and Zope Book made for each Zope release. The "canonical" version (in BackTalk) will be culled for comments at each release and edited. Optimally, when a release is made, all the comments will be addressed and removed from the BackTalk version to start afresh. Here's stuff that I want to do: - Get the ball rolling on the Zope Administrator's Guide again. It's been stalled since last year. I am a big fan of allowing comments to booklike documentation and using those comments to improve later revisions of the documentation. This is actually pretty easy. The *real* challenge is harnessing the energy and work of the community that gets put into HowTos and ZopeLabs tips and whatnot in a canonical place. I'm not really sure how to do this. It's a big job. It requires actually sitting down and reviewing the mass of content that exists, throwing away the old cruft and keeping and categorizing the good stuff. We don't have systems in place that let us do this (or delegate this) effectively. That means that a few motivated individuals will need to bear the brunt of reviewing, editing, categorizing all existing content on Zope.org. Then a system will need to be built (or repurposed -- ZDP) that makes the process easier the second time around. ;-) Then the system needs to be used, which means it needs to be easy.
We have a great community -- that is unfortunately in very many pieces around the world. Nice thing is the diversity, but in some cases the effiency suffers. Should one turn into ZDP, Zope zen, zope newbies, zopelabs or search through the mailinglists? Huh?
Right. This is a hard problem. Good thing we're in the content management business. ;-) Some options for improving the situation right now: - try to find all the best "nuggets" in the form of HowTos and whatnot and try to fold these into the Books (ZB and DevGuide) in the form of new chapters or paragraphs. - kickstart new.zope.org. (zzzz... ;-) New.zope.org has a lot of the features that we've been wanting like workflow for docs and products, if it ever gets out.
What I am suggesting is that together we create a certain set of methods of work, that we all will follow and help others to follow. These will include some etiquette on the mailinglists, howto's and what to do with the information -- for example where to store good code snipplets etc. I know it sounds hard and would require work with many people, especially the great persons who now maintain great sites at zope.org -- but also zopezen.oeg, zopelabs.com, zopenewbies etc.
Well... sure. If you were to come up with a set of guidelines for submitting documentation snipplets, it would be great. I could then put it up on the docs page. Getting folks to follow those directions will be kinda hard, but it'd be a start.
It only requires some time and commitment -- which for most of us equals money. But count the numbers and tell me honestly, would you have any less -- or way much more, if our community for some parts would work like a well oiled machine. Atleast for me, Zope has been a great source of inspiration -- and honestly changed the way I see development... And I would be honoured to give something really valuable back.
Great! I'm up for any suggestions. Whatever we do, it needs to be reasonably low-maintenance and fairly simple (and quick) to implement. - C
Chris McDonough wrote:
(FWIW, as of today, I am at least nominally in charge of documentation at Zope Corporation.)
Cool!
At the moment, I am concentrating on improving the state of the canonical "booklike" docs (the Developer's Guide and the Zope Book). Since it's a part-time job (I'm also doing customer work), it's going to go pretty slowly. But it is going.
Well those are the best kick start material available. I confess that before the zope book I was totally out like _____ ( insert your own item according to your preference ).
- Make the "canonical" place for the Zope Book a BackTalk book in order to allow easy commentability. Currently the Zope Book only allows comments via a SourceForge tracker. The "canonical" version of the Zope Book is currently kept in CVS, which is not readily commentable by the average reader.
This is good. Also I have a suggestion for a new appendix for the book: case examples. I don't know about others, but real life or mock up examples how to design zope applications is really really good material. Even though there are more than one way to do a thing, it would be good to see examples with and after the canonical material. So in the next version of the printed book there would be a cd packed with code-examples ,-)
- Develop a system for producing "release" documentation at each Zope release. The release documentation will be immutable and downloadable in PDF and HTML. For example, there will likely be PDFs and HTML tarballs of the DevGuide and Zope Book made for each Zope release. The "canonical" version (in BackTalk) will be culled for comments at each release and edited. Optimally, when a release is made, all the comments will be addressed and removed from the BackTalk version to start afresh.
What is the status of Zope Help-files - and what is going to happen with them?
That means that a few motivated individuals will need to bear the brunt of reviewing, editing, categorizing all existing content on Zope.org. Then a system will need to be built (or repurposed -- ZDP) that makes the process easier the second time around. ;-) Then the system needs to be used, which means it needs to be easy.
Yes. I remember some time seen some proposition about rating system for zope.org products. That would be nice, since peers would be able to rate and comment on products. Also the feature to send comments to the maker -- and also on the product page, would be nice. Meaning that if there is a product which looks in words good, but in reality is buggy crap, and the writer is long gone.. for example changed company and email address etc.. users could write comments about their luck with product / howto - etc.
- try to find all the best "nuggets" in the form of HowTos and whatnot and try to fold these into the Books (ZB and DevGuide) in the form of new chapters or paragraphs.
Yes. What is your feeling about including examples of using outside products for Zope in these new chapters. For example I am a small fan of the exUserFolder product for providing authentication against postgresql . I wouldnät mind teaming up with some other people and writing a document about the whole exUserFolder as an example... exUserFolder is actually pretty nice specially when one uses it with cmf.
- kickstart new.zope.org. (zzzz... ;-) New.zope.org has a lot of the features that we've been wanting like workflow for docs and products, if it ever gets out.
And there is the warning and achtung on the frontpage... veeery reassuring ,-)
Well... sure. If you were to come up with a set of guidelines for submitting documentation snipplets, it would be great. I could then put it up on the docs page. Getting folks to follow those directions will be kinda hard, but it'd be a start. ... Great! I'm up for any suggestions. Whatever we do, it needs to be reasonably low-maintenance and fairly simple (and quick) to implement.
Well how about if now for starters we would continue discussion on the mailinglist and then you could open a Zwiki-page somewhere, where we all could start the work on these guidelines. I emphasise that compared to many writers and readers on this list I am a newbie, eventhough that I've been playing around with zope almost a year soon. But we don't all have to be too seasoned zopistas to help the cause, since I feel that there are many things that could be told more easily than now. Zope is not that easy, it takes time and commitment -- but sooner or later provides enligthment. -huima, 5 am here. Time to continue writing my work ,-)
So in the next version of the printed book there would be a cd packed with code-examples ,-)
I'm not sure if you've seen it, but the newest Zopes ship with an Examples folder that contains some simple example applications. They're not "real world" apps because they're very simple, but they should get folks "up and going". Maybe there needs to be a Zope Book chapter that explains the examples in the Examples folder.
What is the status of Zope Help-files - and what is going to happen with them?
They continue to be updated every release. The help system implementation might change, but the content will stay the same (or hopefully be improved). Currently the API reference in the Zope Book is generated right from the help files, but it may make sense to make a different book (API reference or something) out of it to give it more exposure.
Yes. I remember some time seen some proposition about rating system for zope.org products. That would be nice, since peers would be able to rate and comment on products. Also the feature to send comments to the maker -- and also on the product page, would be nice. Meaning that if there is a product which looks in words good, but in reality is buggy crap, and the writer is long gone.. for example changed company and email address etc.. users could write comments about their luck with product / howto - etc.
Yes, parts of this exist in new.zope.org. I'm not sure that helps a lot, though. ;-)
Yes. What is your feeling about including examples of using outside products for Zope in these new chapters. For example I am a small fan of the exUserFolder product for providing authentication against postgresql . I wouldnät mind teaming up with some other people and writing a document about the whole exUserFolder as an example...
I think it'd be a pretty big promise for us (Zope Corp) to make a committment to keep chapters devoted to non-Zope-core products up-to-date, so it'd be a little tough to consider putting them in the Zope Book and DevGuide. But I think whole "mini-books" could be devoted to topics like exUserFolder and LocalFS. I'm not sure what form these should be in, but I'm sort of partial to BackTalk for booklike content, and I believe that it's possible for "normal" members to create BackTalk Books on Zope.org, so folks can certainly make use of that if they want to create booklike content. Then again, a HowTo is fine as well. It would just be another document that we needed to review when we did a brute-force review of documentation available on Zope.org. ;-) Our community-contributed documentation management system needs to be simplified and normalized but I know that I can't bite that task off at the moment while I'm concentrating on getting the "official" docs in order. I'm guardedly hopeful somebody will kickstart new.zope.org in the meantime, which might solve a few of the associated problems for us.
Well how about if now for starters we would continue discussion on the mailinglist and then you could open a Zwiki-page somewhere, where we all could start the work on these guidelines.
OK, I took you up on that and I've revived the Documentation Wiki at http://www.zope.org/Wikis/Docs. You need to be logged in to edit. Note that there is already a *lot* of guideline documentation at http://www.zope.org/DocProjects/ (some of which may be outdated), so you should probably look at that before reinventing anything. Thanks a lot! -- Chris McDonough Zope Corporation http://www.zope.org http://www.zope.com "Killing hundreds of birds with thousands of stones"
Hi all, Chris McDonough wrote:
So in the next version of the printed book there would be a cd packed with code-examples ,-)
I'm not sure if you've seen it, but the newest Zopes ship with an Examples folder that contains some simple example applications. They're not "real world" apps because they're very simple, but they should get folks "up and going". Maybe there needs to be a Zope Book chapter that explains the examples in the Examples folder.
What is the status of Zope Help-files - and what is going to happen with them?
They continue to be updated every release. The help system implementation might change, but the content will stay the same (or hopefully be improved). Currently the API reference in the Zope Book is generated right from the help files, but it may make sense to make a different book (API reference or something) out of it to give it more exposure.
perhaps a dumb question, but would it be feasible to create the API-docs straight from the source? OFS/Propertymanager.py is a nice example of a doc-string. A tool like Dieter Maurer's docfinder shows how good incode documentation can be very valuable. This could perhaps be combined with a talkbacked source browsing feature on zope.org. Everytime I have to dive really into the source to find out what happens with my arguments (take ZCatalog.ZopeFindAndApply as an example) I wish I could have some possibility to conserve what I found out. This doesn't have to be perfect, but I *would* have added that information anywhere if I had known where. I don't know how sun creates something like http://java.sun.com/j2se/1.4/docs/api/index.html apart from the $$$$ they spend (which we/zope corp./supposedly everyone else here can't), but every java type I know tells me about the tremendous help it is. I know going that far is not doable, but it really show a direction for making the second half of the learning curve somewhat less steep.
Yes. I remember some time seen some proposition about rating system for zope.org products. That would be nice, since peers would be able to rate and comment on products. Also the feature to send comments to the maker -- and also on the product page, would be nice. Meaning that if there is a product which looks in words good, but in reality is buggy crap, and the writer is long gone.. for example changed company and email address etc.. users could write comments about their luck with product / howto - etc.
Yes, parts of this exist in new.zope.org. I'm not sure that helps a lot, though. ;-)
I don't know if you refer to this very implementation, or to rating/comments in general. I can only speak for myself, but for me, things like that were valuable, be it freshmeat, apps.kde.com, www.kdelook.org. It sometimes even is valuable browsing ordered by score, so that I see if I might have overlooked some gems. cheers, oliver
perhaps a dumb question, but would it be feasible to create the API-docs straight from the source? OFS/Propertymanager.py is a nice example of a doc-string. A tool like Dieter Maurer's docfinder shows how good incode documentation can be very valuable.
It would be. Doug Hellmann's HappyDoc could be used. I'm not entirely certain that the result would be useful, because you'd need to wade through tons of cruft to get to the "good stuff". This is why there is interface documentation... to separate the "private" stuff from the "public" stuff. Interfaces, though they're manual currently and largely only used for docs in Zope 2, play a crucial functional role in Zope 3. This will make a huge impact on their usefulness as documentation because they need to be kept up to date for the system to function properly. All this, said, if someone wanted to devise a system that allowed you to upload a Zope release tarball (or a checkout from CVS) and run HappyDoc against it to get HTML files and put them up for browsing, I'm sure it would be useful to a lot of folks.
This could perhaps be combined with a talkbacked source browsing feature on zope.org. Everytime I have to dive really into the source to find out what happens with my arguments (take ZCatalog.ZopeFindAndApply as an example) I wish I could have some possibility to conserve what I found out.
Would having the API reference in BackTalk be a start towards this?
This doesn't have to be perfect, but I *would* have added that information anywhere if I had known where. I don't know how sun creates something like http://java.sun.com/j2se/1.4/docs/api/index.html apart from the $$$$ they spend (which we/zope corp./supposedly everyone else here can't), but every java type I know tells me about the tremendous help it is. I know going that far is not doable, but it really show a direction for making the second half of the learning curve somewhat less steep.
Have you seen the API reference in the Zope Book and the Help System? It's maybe not as comprehensive, but this is its goal. How can it be improved?
I don't know if you refer to this very implementation, or to rating/comments in general. I can only speak for myself, but for me, things like that were valuable, be it freshmeat, apps.kde.com, www.kdelook.org. It sometimes even is valuable browsing ordered by score, so that I see if I might have overlooked some gems.
Yup. A generalized ratings systems would be helpful. - C
Thanks for taking your time to answer. Chris McDonough wrote:
perhaps a dumb question, but would it be feasible to create the API-docs straight from the source? OFS/Propertymanager.py is a nice example of a doc-string. A tool like Dieter Maurer's docfinder shows how good incode documentation can be very valuable.
It would be. Doug Hellmann's HappyDoc could be used. I'm not entirely certain that the result would be useful, because you'd need to wade through tons of cruft to get to the "good stuff". This is why there is interface documentation... to separate the "private" stuff from the "public" stuff.
Interfaces, though they're manual currently and largely only used for docs in Zope 2, play a crucial functional role in Zope 3. This will make a huge impact on their usefulness as documentation because they need to be kept up to date for the system to function properly.
This is definately something which will greatly improve the work of product authors and others. Though I have no right to demand something from the people working on zope 3, it would IMO be great if zope3's API-docs could be based on the source of the interfaces. There is already a happydoc'ed zope documentation at http://www.zope.org/Documentation/Developer/ZopeSrcDocs for instance, though it's 2.3.2 only. I'm not familiar how happydoc works, but perhaps it's possible to use just the interfaces right now, or to switch the output to be less verbose - similar like the api-doc is right now. Or, hopefully, it wouldn't be too much work to adapt happdoc to zope's needs. <wet developer dream> Or integrate a "zhappydoc" with zope to generate the api-docs for zope's HelpSys automatically, *including* all installed products. </wet developer dream> What would be needed though is a short description of the arguments of methods in the doc-strings.
All this, said, if someone wanted to devise a system that allowed you to upload a Zope release tarball (or a checkout from CVS) and run HappyDoc against it to get HTML files and put them up for browsing, I'm sure it would be useful to a lot of folks.
Well, obviously somebody has done it, once. I gave it a try some time ago, failed, and didn't have the time to persue. I did know nothing about happydoc.
This could perhaps be combined with a talkbacked source browsing feature on zope.org. Everytime I have to dive really into the source to find out what happens with my arguments (take ZCatalog.ZopeFindAndApply as an example) I wish I could have some possibility to conserve what I found
out.
Would having the API reference in BackTalk be a start towards this?
This would be great, even if zope 3 is out, IMO, because it could help commiters to gather missing material. Eventually one could account missing/faulty interface comments as (noncritical) bugs, whereby there should be written guidelines as to what has to be in said comments (e.g. "has to include description of arguments"). So the collector would get a nice tool to keep the API docs in shape.
[java api docs example]
Have you seen the API reference in the Zope Book and the Help System? It's maybe not as comprehensive, but this is its goal. How can it be improved?
Unfortunatly I'm still stuck mainly at zope 2.3.3 and didn't do too much with newer zopes, although IIRC the API docs in HelpSys didn't change. I like the API reference in the Help System very much, esp. it's layout is better IMO than the online version of the zope book, but both are not complete (as a search for ZopeFind reveals). But, I use the API doc in zope for nearly 30% of my information needs, 60% is reading zope's source and the rest is mailing lists etc.. With a more or less complete API documentation this could be shifted to 80%/10% I estimate. Fortunatly python source is very readable... cheers, oliver
This is definately something which will greatly improve the work of product authors and others. Though I have no right to demand something from the people working on zope 3, it would IMO be great if zope3's API-docs could be based on the source of the interfaces.
They almost certainly will be.
Well, obviously somebody has done it, once. I gave it a try some time ago, failed, and didn't have the time to persue. I did know nothing about happydoc.
Ah ok. Well, all the tools are available to whatever motivated individual wants to generate docs from source.
Unfortunatly I'm still stuck mainly at zope 2.3.3 and didn't do too much with newer zopes, although IIRC the API docs in HelpSys didn't change. I like the API reference in the Help System very much, esp. it's layout is better IMO than the online version of the zope book, but both are not complete (as a search for ZopeFind reveals). But, I use the API doc in zope for nearly 30% of my information needs, 60% is reading zope's source and the rest is mailing lists etc.. With a more or less complete API documentation this could be shifted to 80%/10% I estimate. Fortunatly python source is very readable...
Hopefully being able to comment on the online version of the API docs will help us figure out what's missing. Thanks! -- Chris McDonough Zope Corporation http://www.zope.org http://www.zope.com "Killing hundreds of birds with thousands of stones"
At the risk of stating the obvious, are you folks aware that pydoc comes with python these days? It produces javadoc-like html as well as man pages (try pydoc pydoc from a prompt to see what I mean) A little tool that everyone should know of. seb On Wed, 2002-04-03 at 15:35, Chris McDonough wrote:
This is definately something which will greatly improve the work of product authors and others. Though I have no right to demand something from the people working on zope 3, it would IMO be great if zope3's API-docs could be based on the source of the interfaces.
They almost certainly will be.
Well, obviously somebody has done it, once. I gave it a try some time ago, failed, and didn't have the time to persue. I did know nothing about happydoc.
Ah ok. Well, all the tools are available to whatever motivated individual wants to generate docs from source.
Unfortunatly I'm still stuck mainly at zope 2.3.3 and didn't do too much with newer zopes, although IIRC the API docs in HelpSys didn't change. I like the API reference in the Help System very much, esp. it's layout is better IMO than the online version of the zope book, but both are not complete (as a search for ZopeFind reveals). But, I use the API doc in zope for nearly 30% of my information needs, 60% is reading zope's source and the rest is mailing lists etc.. With a more or less complete API documentation this could be shifted to 80%/10% I estimate. Fortunatly python source is very readable...
Hopefully being able to comment on the online version of the API docs will help us figure out what's missing.
Thanks!
-- Chris McDonough Zope Corporation http://www.zope.org http://www.zope.com "Killing hundreds of birds with thousands of stones"
_______________________________________________ Zope maillist - Zope@zope.org http://lists.zope.org/mailman/listinfo/zope ** No cross posts or HTML encoding! ** (Related lists - http://lists.zope.org/mailman/listinfo/zope-announce http://lists.zope.org/mailman/listinfo/zope-dev )
One of the key problems is that a lot of excellent and helpful material exists but can't be easily found. For example, the mailing list has answers to a lot of questions, but it is hard to invent the right set of search terms to end up with the gold nuggets that actually talk about your problem. The same goes with the how-to's etc. Now you have only two ways: browse the subjects and guess, or do full text searches. Maybe a key thing in making the community contributions more useful could be to try to build more shared structure for the issues that are discussed, and start to use common descriptions for the issues. I am not sure how to do that...but I believe that contributions from both 1) those how know ZOPE and CMF well enough to put pieces in their most proper place and 2) those who know so little that they can't recognize what their problem really relates to have to come together in this - but maybe in a fashion that eventually is coordinated by one of those who is involved in the development of future directions. The common decsriptions need to have a good spectrum of levels of detail, so that if one knows exactly what one is talking about it can be specified, but at the same time it can be bound together with other issues in the same family. I think that in the first step, the mailing list messages could simply be further qualified with some keyphrases (one or more phrases which each contain one or more keywords that describe the issue in possibly increasing detail as in "workflow, customize", "xxx, x111, x222") by all, and maybe some of the more experienced ones could try to start the practice and establish some good examples of keyphrase structures. This annotation should of course take place already when messages are posted, but could be revised later in a database. The second component would be some kind of rating - so that those who find a snippet useful or wrong could indicate that (but I am not sure how to do this so that there would be some kind of quality control in the quality control). Eventually, a nice zope product can be written that makes it easy to organize and search these messages in an elegant way; this would also make a great database for structured, comprehensive, edited FAQ and book development. khk ...... At 21:06 -0500 1.4.2002, Chris McDonough wrote:
A while a ago there was discussion about the community stalling and the state of the documentation. As far as I can remember and see, there wasn't really any agreements or solutions what to do -- so I raise the question again -- and propably aim it to the people at Zope corp., what we -- noble users -- could do to help your work on documentation?
...
We have a great community -- that is unfortunately in very many pieces around the world. Nice thing is the diversity, but in some cases the effiency suffers. Should one turn into ZDP, Zope zen, zope newbies, zopelabs or search through the mailinglists? Huh?
Right. This is a hard problem. Good thing we're in the content management business. ;-)
Some options for improving the situation right now:
- try to find all the best "nuggets" in the form of HowTos and whatnot and try to fold these into the Books (ZB and DevGuide) in the form of new chapters or paragraphs.
- kickstart new.zope.org. (zzzz... ;-) New.zope.org has a lot of the features that we've been wanting like workflow for docs and products, if it ever gets out.
What I am suggesting is that together we create a certain set of methods of work, that we all will follow and help others to follow. These will include some etiquette on the mailinglists, howto's and what to do with the information -- for example where to store good code snipplets etc. I know it sounds hard and would require work with many people, especially the great persons who now maintain great sites at zope.org -- but also zopezen.oeg, zopelabs.com, zopenewbies etc.
Well... sure. If you were to come up with a set of guidelines for submitting documentation snipplets, it would be great. I could then put it up on the docs page. Getting folks to follow those directions will be kinda hard, but it'd be a start.
I think that in the first step, the mailing list messages could simply be further qualified with some keyphrases (one or more phrases which each contain one or more keywords that describe the issue in possibly increasing detail as in "workflow, customize", "xxx, x111, x222") by all, and maybe some of the more experienced ones could try to start the practice and establish some good examples of keyphrase structures. This annotation should of course take place already when messages are posted, but could be revised later in a database.
I think this is a noble idea, but I also believe that it would be very difficult to expect of folks. ;-) Open source software development and support is chaos. People can't even remember what day it is or whether they had lunch most of the time when they're developing software, much less how the Zope maillist taxonomy works. An explicit keyword list in email messages would be very difficult to enforce, and most folks wouldn't pay much attention. Now Bill's and Andy's idea where folks used an email client to post a FAQ explicitly might work pretty well.. this would work because individuals could do it without much fuss.
The second component would be some kind of rating - so that those who find a snippet useful or wrong could indicate that (but I am not sure how to do this so that there would be some kind of quality control in the quality control).
ZopeLabs has this. The Python Cookbook at ActiveState also has this. Thanks! - C
"Chris McDonough" <chrism@zope.com> writes:
People can't even remember what day it is or whether they had lunch most of the time when they're developing software, much less how the Zope maillist taxonomy works.
Oh thank you, thank you.. and I thought that was just me :)
Chris McDonough writes:
.... - Develop a system for producing "release" documentation at each Zope release. The release documentation will be immutable and downloadable in PDF and HTML. For example, there will likely be PDFs and HTML tarballs of the DevGuide and Zope Book made for each Zope release. Very good!
Dieter
participants (7)
-
Chris McDonough -
Dieter Maurer -
Heimo Laukkanen -
Kari-Hans Kommonen -
Oliver Bleutgen -
seb bacon -
Simon Michael