Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
| 1 2 3 4 |
|
vedaw
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by JoAnna Springsteen
I guess once we get our gap assessments, we can pick the top 2 or 3 things
for each section? I'll add this to the list of things we'd like to see for the next round. Since we'll be moving to the world of Plone 3, at least we'll get static portlets, which means this will be modifiable by anyone with docteam rights, so it's not likely to get stale. Joanna, I know I'm a total nag, but when are we going to post the official list of editors? Is there a reason we're not doing it already? I'm just wondering because I myself don't know who all of the editors are, much less how to find some of them if I want to refer an author to them... And, I'm also noticing that some of the authors did not report back on their progress on the notes from the docteam meeting on 11/5. Does this mean they are not doing their gap analyses? Can we follow up with the rest of the editors so that we're more likely to stay on track? Thanks! - Veda On 11/19/08 9:47 AM, "JoAnna Springsteen" <[hidden email]> wrote: > On Wed, Nov 19, 2008 at 11:42 AM, Veda Williams <[hidden email]> wrote: >> I saw something similar here: >> >> http://www.youtube.com/user/YouTubeHelp >> >> The idea is to post a list of what documentation you're looking for, >> probably in a portlet. In our case, we'd also want to list the person to >> contact if you want to work on that project. >> >> Just a thought... >> > > I remember you showed this to me before...can't remember what I said > then but it does strike me as a good idea. And our gap analysis from > the section assessments could help us compile a list. > Kind of like a Documentation bounty....er, without the financial > reward. (good karma and helping others is enough of a reward, right?) ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
JoAnna Springsteen
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
On Wed, Nov 19, 2008 at 12:37 PM, Veda Williams <[hidden email]> wrote:
> I guess once we get our gap assessments, we can pick the top 2 or 3 things > for each section? I'll add this to the list of things we'd like to see for > the next round. +1 > Since we'll be moving to the world of Plone 3, at least we'll get static > portlets, which means this will be modifiable by anyone with docteam rights, > so it's not likely to get stale. great. > Joanna, I know I'm a total nag, but when are we going to post the official > list of editors? Is there a reason we're not doing it already? I'm just > wondering because I myself don't know who all of the editors are, much less > how to find some of them if I want to refer an author to them... It's up and on the site, just not published. Should be in the contributing to plone section. Darci and Matt made fun of my tables though and I haven't had a chance to go back and do it. Should be docs for the list of editors and one for their responsibilities. Let me double check them this afternoon and I'll submit them and then ping you to publish them. > And, I'm also noticing that some of the authors did not report back on their > progress on the notes from the docteam meeting on 11/5. Does this mean they > are not doing their gap analyses? Can we follow up with the rest of the > editors so that we're more likely to stay on track? I've followed up individually and everyone is working on things...some are just getting started and need lots of extra support. They have strict instructions to keep in touch and let me know if they need anything. I'll check in with everyone again on Friday. ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
vedaw
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Christopher Warner
Some javascript/style in this post has been disabled (why?)
In response to your comment that we are lacking a sysadmin guide, you are correct. We’d love to have something on plone.org/documentation along these lines. I thought you’d also like to know that Packt Publishing (the same company responsible for publishing Professional Plone Development, the upcoming Practical Plone book, and next year’s Theming for Plone) is looking for someone to write a sysadmin book. Contact information is below if anyone has an itch they want to scratch for the community. Cheers, - Veda >> You are receiving this mail because Kshipra Singh >> [hidden email] >> is sending feedback about the site administered by you at >> http://www.theploneblog.org. >> The message sent was: >> >> Hi, I am writing to you for Packt Publishing, the publishers of computer >> related books. We are planning to publish a book on Plone, titled Plone Site >> Admin, as we believe that there exists a lucrative market for the same. While >> trying to find out some potential authors for this book, I came across your >> blog which tells me about your expertise in Plone. This gives me an >> impression that a member of your team might be interested in authoring this >> book. The book will be a reference guide to all the tasks of a Plone admin. >> It would focus more on those users of Plone who do not have high competencies >> in site administration. The book will aid them in becoming competent in >> getting their Plone sites up, running, and customized with minimal peripheral >> knowledge. It will include topics like a.. Background (about, prerequisites, >> preparation) b.. Site basics (navigation, content types) c.. Administration >> (users, objects) d.. Optimization (caching, load management) e.. Maintenance >> (backups, packing) f.. Appearance (style and customization) The reader is >> expected to know basic Python programming and should be at least an user of >> Plone sites. To help you know the way things work at Packt: -The editorial >> team at Packt works with the author through out the project. -We offer a >> royalty of 15% and an advance against the same. -The marketing team at Packt >> ensures that the book is well promoted -We donate a percentage of revenue >> coming from the sales of the book to the Open Source project on which it is >> based. We have donated more than 100 000 dollars since inception. Could you >> please let me know if the idea of authoring such a book sounds interesting to >> any of your team members? Should you have any queries, please feel free to >> let me know. Thanks Kshipra Singh Author Relationship Manager Packt >> Publishing www.PacktPub.com skype: kshiprasingh15 On 11/18/08 1:13 PM, "Warner, Christopher" <[hidden email]> wrote:
------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Dylan Jay-4
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by vedaw
> -----Original Message----- > From: Veda Williams [mailto:[hidden email]] > Sent: Thursday, 20 November 2008 4:42 AM > To: Dylan Jay; JoAnna Springsteen > Cc: [hidden email]; 'Warner, Christopher' > Subject: Re: [Plone-docs] If core code is undocumented it's broken > (Was:where should developer documentation go?) > > I saw something similar here: > > http://www.youtube.com/user/YouTubeHelp > > The idea is to post a list of what documentation you're looking for, > probably in a portlet. In our case, we'd also want to list the person to > contact if you want to work on that project. I think this is still thinking about PHC type documentation. Small little docs that are unrelated to each other. Why not organise the gap analysis and the good documentation into a book based on subject areas. And then do as you suggest, have someone to contact for the chapters that haven't been written yet. For example http://argouml-stats.tigris.org/documentation/manual-0.24/ch04s05.html#d0e38 27 I think it's a crying shame that the only way to make sense of Plone is via a book and most of the books are commercial. What does that say about our community? > Just a thought... > > On 11/18/08 7:19 PM, "Dylan Jay" <[hidden email]> wrote: > > > > > One way we could do that is publish earlier rather than later. > > That whole roadmap pretty much falls on the doc team to implement it > alone, > > which is huge amount of work as veda hinted. > > > > This is just an idea but it might solve the getting people to help > problem. > > > > We could release the manuals uncompleted like argouml has > > > > http://argouml-stats.tigris.org/documentation/manual-0.26/ > > > > with (to be written) all over the place. > > > > It might seem unprofessional but it would mean that people could see a > space > > they really want to add to and put their hand up. Instead of sitting > their > > grumbling about the confusion of documentation. Or worse still create > yet > > more documents in the PHC soup. > ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Ricardo Newbery-2
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
On Nov 19, 2008, at 1:47 PM, Dylan Jay wrote: >> -----Original Message----- >> From: Veda Williams [mailto:[hidden email]] >> >> I saw something similar here: >> >> http://www.youtube.com/user/YouTubeHelp >> >> The idea is to post a list of what documentation you're looking for, >> probably in a portlet. In our case, we'd also want to list the >> person to >> contact if you want to work on that project. > > I think this is still thinking about PHC type documentation. Small > little > docs that are unrelated to each other. > > Why not organise the gap analysis and the good documentation into a > book > based on subject areas. And then do as you suggest, have someone to > contact > for the chapters that haven't been written yet. > For example > http://argouml-stats.tigris.org/documentation/manual-0.24/ch04s05.html#d0e38 > 27 Why shift the burden of proof? You are proposing a radical change to the way Plone.org documentation is written and organized. The burden is upon you to convince people to accept your vision. So let me rephrase your question... What advantage does "organizing the gap analysis and the good documentation into a book based on subject areas" have over publishing the gap analysis and encouraging contributors to write separate stand- alone docs to fill the gaps? > I think it's a crying shame that the only way to make sense of Plone > is via > a book and most of the books are commercial. What does that say > about our > community? Books are not the only way to make sense of Plone. Sure, there are some weaknesses in the current documentation but let's not overstate the case. Ric ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Rok Garbas
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Carsten Senger-3
On Wed, Nov 19, 2008 at 7:05 PM, Carsten Senger <[hidden email]> wrote:
> > from what I understand API is being updated using sphinx. > > I'm sure the docteam+contributors are on the right track, but at the > risk of repeating discussions that happend before, are documented in the > wiki or are in everybodys head: > > The important part for isn't API documentation (btw that doesn't mean > that sphinx is a pure apidoc-generator), it should be a "developers > manual" in a book style. With chapters that introduce basic concepts and > techniques, that describe parts of plone or specific tasks/topics and > maybe a bunch of receipts/code examples/links attached to every chapter. > > It has to be structured for developers and needs a real toc, like > manuals now have in the phc, and at best an index. It does not have to > be written from scratch. It can start with many texts that are in phc now. > > The whole book should be bound to a plone version, either released or > the next to be released. It's no problem if it contains unfinished texts > or texts marked as "maybe or partial outdated". > > So a basic important thing is that the developers manual is structured > and the structure is maintained as it grows. This is surely true for all > documentation areas, and independed of the tool it is maintained with. > > I'm not sure that sphinx is the right tool, but that's another question. > thats what sphinx effort is all about. to provide toc structured developers guide / manual for plone. first step is to pull all docstring, doctests and see what documentation is missing. at the same time some reasonable structure is needed like - as you said - a book. eventualy some howtos, manual, tutorials from plone.org/documentation could be pulled in. this documentation will be (99%) written by developers, so it should be developers friendly. this sphinx thingy will also cover api reference. i've checked a lot of documentating software (zope integrated apidoc, epydoc, ...) and sphinx rule them all. but i would also like to hear if you have some better tool in mind. p.s. this weekend i'll be working on fully document one of plone.* packages, if anybody want to join me find me on #plone -- Rok Garbas http://sharbas.blogspot.com/ ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Christopher Warner
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by vedaw
Some javascript/style in this post has been disabled (why?)
I’d love to write a book on it only if my content was freely available. I’ll mull this over but really I’ve been spending some time digesting what currently exist now and how I can move forward in helping with the current situation. The idea of all these books is great but there is also the absence of a comprehensive manual that gives a good general overview of things for new blood. How it all fits together and such, that is more important to me. In earlier messages I gave a link to a manual on the drupal site called Getting Started. I dislike Drupal with a passion but if we take a look at the table of contents it includes a very nice overview of the system. Installation, Basic Content Management, Administration, Site Building, User Management, Concepts etc etc. I’m not sure how we are currently structuring for a manual like this and having something like this would be what I believe to be a big step from what we currently have now. -- Christopher Warner Manager, Content Management Systems New York Media | 75 Varick St, 4th Fl New York, NY 10013 phone: 212.508.0542 cell: 646.334.6780 On 11/19/08 1:55 PM, "Veda Williams" <veda@...> wrote: Hi Christopher (et al), ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
vedaw
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
Some javascript/style in this post has been disabled (why?)
I’m also leaning towards a more consolidated manual system, with documents like the one Israel is working on serving as a first pass at what this structure (TOC) might look like for a Getting Started manual. Right now, that doc links out to existing docs, but perhaps over time those docs could be integrated into it as a single document with topics and subtopics. It’ll take time, but if we make a decision to move in that general direction, eventually we will get there. Certainly, we have the End User Manual, the Theming Reference, and potentially a Developer Reference via Sphinx, so I’m starting to see a pattern forming. Without starting a firestorm, do we have consensus that manuals are where we are going? Cheers, - Veda On 11/20/08 9:22 AM, "Warner, Christopher" <[hidden email]> wrote: Hey Veda, ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Marco De Vitis
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Dylan Jay-4
Il 19-11-2008 4:19, Dylan Jay ha scritto:
> One way we could do that is publish earlier rather than later. > That whole roadmap pretty much falls on the doc team to implement it alone, > which is huge amount of work as veda hinted. > > This is just an idea but it might solve the getting people to help problem. > > We could release the manuals uncompleted like argouml has > > http://argouml-stats.tigris.org/documentation/manual-0.26/ > > with (to be written) all over the place. Hi, sorry but I have to say I personally hate this. I hate it when I start reading a doc, browse through its juicy table of contents thinking "Hmm, I'm gonna learn lots of great stuff here!", but then, soon after a first newbie-stuff-I-already-knew part, I start banging on "to be written" pages and do not find any of the great contents I expected to be there. It happened to me a couple of times at least, while reading docs for some other open source project, and it left me with a bitter taste of "useless documentation". I also don't think it really exhorts people to write missing content, because people reading the doc are most probably not yet able to contribute content, while people possessing the required expertise can contribute content anyway if they feel like doing it, regardless of any "to be written" sign. Sorry if this is my only post in recent times but I'm still trying to clear up the mess in my life. I still love Plone and love docs, but can't find the time to contribute. I'm catching up with all recent messages here right now, and I'm amazed at the recent activity, you're all doing a great job! -- Ciao, Marco. ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
vedaw
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
I agree, it feels unprofessional to me. It's like posting a website with
"coming soon" on the homepage... Either you're ready to put it up or you aren't, but doing it too soon makes it look half-assed. I'm not opposed, however, to posting a "wish list" of docs we'd like to see written, in order of importance. On 11/21/08 4:22 PM, "Marco De Vitis" <[hidden email]> wrote: > Il 19-11-2008 4:19, Dylan Jay ha scritto: >> We could release the manuals uncompleted like argouml has >> >> http://argouml-stats.tigris.org/documentation/manual-0.26/ >> >> with (to be written) all over the place. > > Hi, sorry but I have to say I personally hate this. > I hate it when I start reading a doc, browse through its juicy table of > contents thinking "Hmm, I'm gonna learn lots of great stuff here!", but > then, soon after a first newbie-stuff-I-already-knew part, I start > banging on "to be written" pages and do not find any of the great > contents I expected to be there. > > I also don't think it really exhorts people to write missing content, > because people reading the doc are most probably not yet able to > contribute content, while people possessing the required expertise can > contribute content anyway if they feel like doing it, regardless of any > "to be written" sign. ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Dylan Jay-4
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Marco De Vitis
> -----Original Message-----
> From: Marco De Vitis [mailto:[hidden email]] > Sent: Saturday, 22 November 2008 11:23 AM > To: [hidden email] > Subject: Re: [Plone-docs] If core code is undocumented it's broken > (Was:where should developer documentation go?) > > Il 19-11-2008 4:19, Dylan Jay ha scritto: > > > One way we could do that is publish earlier rather than later. > > That whole roadmap pretty much falls on the doc team to implement it > alone, > > which is huge amount of work as veda hinted. > > > > This is just an idea but it might solve the getting people to help > problem. > > > > We could release the manuals uncompleted like argouml has > > > > http://argouml-stats.tigris.org/documentation/manual-0.26/ > > > > with (to be written) all over the place. > > Hi, sorry but I have to say I personally hate this. > I hate it when I start reading a doc, browse through its juicy table of > contents thinking "Hmm, I'm gonna learn lots of great stuff here!", but > then, soon after a first newbie-stuff-I-already-knew part, I start > banging on "to be written" pages and do not find any of the great > contents I expected to be there. > It happened to me a couple of times at least, while reading docs for > some other open source project, and it left me with a bitter taste of > "useless documentation". > > I also don't think it really exhorts people to write missing content, > because people reading the doc are most probably not yet able to > contribute content, while people possessing the required expertise can > contribute content anyway if they feel like doing it, regardless of any > "to be written" sign. > > Sorry if this is my only post in recent times but I'm still trying to > clear up the mess in my life. I still love Plone and love docs, but > can't find the time to contribute. I'm catching up with all recent > messages here right now, and I'm amazed at the recent activity, you're > all doing a great job! > > -- > Ciao, > Marco. Ok. What if we made the new manuals Plone.org members only viewing? Newbies and anon viewers wouldn't see them. What I'm trying to avoid is this pressure to have a fully complete and beautiful document before anyone else sees it. We need beta and alpha testing for manuals so as to get feedback and help from others in the community rather than keeping so much workload on the doc team. To be honest I think a lot of developers have given up hope of seeing decent developer documentation out of Plone.org. I'd like to inspire them that there is hope at the end of the tunnel. ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Mikko Ohtamaa
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
|
> Hi, sorry but I have to say I personally hate this. > I hate it when I start reading a doc, browse through its juicy table of > contents thinking "Hmm, I'm gonna learn lots of great stuff here!", but > then, soon after a first newbie-stuff-I-already-knew part, I start > banging on "to be written" pages and do not find any of the great > contents I expected to be there. > I agree, it feels unprofessional to me. It's like posting a website with > "coming soon" on the homepage... Either you're ready to put it up or you > aren't, but doing it too soon makes it look half-assed. I'm not opposed, > however, to posting a "wish list" of docs we'd like to see written, in order > of importance. To be honest, I don't really believe Plone core community could make any decent output in the traditional way. As we see from the past, this thing has not progressed for several years, besides having email wars @ plone-docs now and then. Doc team doesn't have enough insight and they need to worry about newbies, core team has to worry abouts bugs and technical progress. > while people possessing the required expertise can contribute content anyway if they feel like doing it, regardless of any "to be written" sign. No they can't contribute. They need to make an plone.org account, log in, read contribution guidelines, fight with the review team and *they can't contribute to existing docs*. That's the trick of Wikipedia - to make contribution barrier so low that it is an attractive opinion to spend your 5 minutes to contribute/polish the little thing. You can either have 5 people writing the documentation or 100 people writing the documentation and 5 people managing it. I don't care if it's disorganized or doesn't satisfy the perfectionism taste of doc team - having something is better than having nothing in this case. Unlike code, manuals don't need "testing" or beta stage - they just need fixing and contributions. Little red links there and here don't matter. Personally you can count my contributions out from anything but Wiki. I am tired with the state of documentation and how hard it to get anything fixed there. Putting docs to Sphinx besides SVN won't make any good for the contribution barrier. Let's make it a race: doc team can start write its perfect manual now and meanwhile we just have a wiki, ok? It takes 5 minutes from me or Dylan to set up a wiki if we can get semiofficial blessing for this with having a plone.org domain name. developers.plone.org anyone? Thanks, Mikko |
||
|
|
JoAnna Springsteen
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Dylan Jay-4
> Ok. What if we made the new manuals Plone.org members only viewing? Newbies
> and anon viewers wouldn't see them. This is how it currently exists, except you have to be a member of the doc team group on plone.org. > What I'm trying to avoid is this pressure to have a fully complete and > beautiful document before anyone else sees it. Doc team members can see the doc as soon as it's created. And yes, we do sneak peaks while documents are in progress. > We need beta and alpha testing for manuals so as to get feedback and help > from others in the community rather than keeping so much workload on the doc > team. This is what being a part of the doc team means. We're there to review docs. We've changed it recently so that only editors can publish but all doc team members can still look and review and add comments. And our review queue is nearly empty (thanks Israel!) so it hasn't created a bottleneck either. >To be honest I think a lot of developers have given up hope of seeing > decent developer documentation out of Plone.org. I'd like to inspire them > that there is hope at the end of the tunnel. I've seen just the opposite. This year at the conference I had more people approach me than ever that wanted to know how they could contribute and what did they think of this idea or that for docs. The biggest issue with getting developers to write docs is time. They're busy coding and working on PLIPs instead of documenting. I think it's more of an issue of getting people to make the time than anything else. ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Ricardo Newbery-2
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Mikko Ohtamaa
On Nov 21, 2008, at 5:33 PM, Mikko Ohtamaa wrote: > To be honest, I don't really believe Plone core community could make > any > decent output in the traditional way. As we see from the past, this > thing > has not progressed for several years, besides having email wars @ > plone-docs > now and then. Doc team doesn't have enough insight and they need to > worry > about newbies, core team has to worry abouts bugs and technical > progress. Again, this is overstating the case. The doc situation has been improving steadily for awhile now and the team appears to have plenty of productive momentum. IMO, there is still plenty of room for improvement but frankly it's not terribly productive (nor fair) to say the group lacks insight just because some reasonable concerns are expressed about an alternative you are advocating. >> while people possessing the required expertise can contribute content >> anyway if they feel like doing it, regardless of any "to be >> written" sign. > > No they can't contribute. They need to make an plone.org account, > log in, > read contribution guidelines, fight with the review team and *they > can't > contribute to existing docs*. That's the trick of Wikipedia - to make > contribution barrier so low that it is an attractive opinion to > spend your 5 > minutes to contribute/polish the little thing. You can either have 5 > people > writing the documentation or 100 people writing the documentation > and 5 > people managing it. I don't care if it's disorganized or doesn't > satisfy the > perfectionism taste of doc team - having something is better than > having > nothing in this case. Unlike code, manuals don't need "testing" or > beta > stage - they just need fixing and contributions. Little red links > there and > here don't matter. The process to contribute to *existing* documents could maybe use some improvement. Right now, someone can create a brand new doc for review easily enough. Perhaps we need to make it easier for someone to create a new version of an existing doc.... the Iterate diff feature could make it fairly easy for reviewers to review the changes. > Personally you can count my contributions out from anything but > Wiki. I am > tired with the state of documentation and how hard it to get > anything fixed > there. Putting docs to Sphinx besides SVN won't make any good for the > contribution barrier. > > Let's make it a race: doc team can start write its perfect manual > now and > meanwhile we just have a wiki, ok? It takes 5 minutes from me or > Dylan to > set up a wiki if we can get semiofficial blessing for this with > having a > plone.org domain name. developers.plone.org anyone? Why make this into an adversarial thing? It seems to me that the doc team might possibly be open to the idea of setting up a separate open- editing sandbox (although I'm personally skeptical about the idea) and I believe there are some proposals floating that are being taken seriously. Perhaps it would be more productive to give the doc team some time to mull the options and actually make a decision before ratcheting up the rhetoric. :-) Peace, Ric ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Guy Heckman
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
As an implementor and small-time product developer I find a wiki the
way to go. Weblion's wiki solution has served us well over the years and judging from search results I'm sure more than a few people on this list have benefitted from it too. My major justification for this approach is timeliness - I hate having to read down through all of the comments on a piece of documentation/howto to find what is different in 3.1 when the original page was written for 2.5 (or any variation thereof). I think the documentation team is doing a great job but I have my reservations about the documentation keeping up with the pace of Plone development, much less maintaining all of the variations brought about by version changes, in a closed documentation model. My second argument is more philosophical - why have a closed documentation process for an open source system? Third and last - many OS projects have switched to wikis for documentation and it seems to work, has anyone approached any other OS documentation teams get their opinion or reasoning for doing what they are doing? I do believe that there should be 'official' Plone manuals but I would think that it could be much more manageable if it drew from an open and easily accessed/editable centralized source. Let the community do the submitting & vetting of the materials so the the doc team can concentrate on form, organization, and presentation. On Nov 21, 2008, at 10:07 PM, Ricardo Newbery wrote: > Snip - saving paper ;-) Guy Heckman Systems Design Specialist Programming & Development Research, Instruction & Information Technology (RIIT) Group Smeal College of Business The Pennsylvania State University 11 Business Building University Park, PA 16827 Phone: 814-863-9819 Fax: 814-865-1845 http://www.smeal.psu.edu [hidden email] ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Dylan Jay-4
()
Re: If core code is undocumented it's broken(Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Ricardo Newbery-2
I think docs have improved in areas OTHER than developer documentation,
which if anything has got worse as more and more contradictory docs have been generated. I think that developers such as Nikko and myself are getting frustrated because we see that an incremental approach for developer docs is not enough. Most of the responses of the doc team seem to be similar to yours Ricardo. There isn't much of a problem and only tweaks need to be made. This situation is all the more urgent because lots of work needs to be done to make Plone better and yet it is becoming harder and harder for new developers to get up to speed on Plone. I know several people personally who have tried very hard to use Plone on professional projects and will probably now never use Plone again. I've looked at this issue in depth as I have bet my business on Plone, and there are other aspects of Plone that will help Plone be simpler to learn (most of which Martin covered in his talk at the conference) but developer documentation is still the best bang for our buck to improve this situation and still the area where the doc teams seems think that nothing is fundamentally wrong. Nothing that extra work from editors can't fix. > -----Original Message----- > From: Ricardo Newbery [mailto:[hidden email]] > Sent: Saturday, 22 November 2008 2:08 PM > To: Mikko Ohtamaa > Cc: [hidden email] > Subject: Re: [Plone-docs] If core code is undocumented it's > broken(Was:where should developer documentation go?) > > > On Nov 21, 2008, at 5:33 PM, Mikko Ohtamaa wrote: > > > To be honest, I don't really believe Plone core community could make > > any > > decent output in the traditional way. As we see from the past, this > > thing > > has not progressed for several years, besides having email wars @ > > plone-docs > > now and then. Doc team doesn't have enough insight and they need to > > worry > > about newbies, core team has to worry abouts bugs and technical > > progress. > > > Again, this is overstating the case. The doc situation has been > improving steadily for awhile now and the team appears to have plenty > of productive momentum. IMO, there is still plenty of room for > improvement but frankly it's not terribly productive (nor fair) to say > the group lacks insight just because some reasonable concerns are > expressed about an alternative you are advocating. > > > > > >> while people possessing the required expertise can contribute content > >> anyway if they feel like doing it, regardless of any "to be > >> written" sign. > > > > No they can't contribute. They need to make an plone.org account, > > log in, > > read contribution guidelines, fight with the review team and *they > > can't > > contribute to existing docs*. That's the trick of Wikipedia - to make > > contribution barrier so low that it is an attractive opinion to > > spend your 5 > > minutes to contribute/polish the little thing. You can either have 5 > > people > > writing the documentation or 100 people writing the documentation > > and 5 > > people managing it. I don't care if it's disorganized or doesn't > > satisfy the > > perfectionism taste of doc team - having something is better than > > having > > nothing in this case. Unlike code, manuals don't need "testing" or > > beta > > stage - they just need fixing and contributions. Little red links > > there and > > here don't matter. > > > The process to contribute to *existing* documents could maybe use some > improvement. Right now, someone can create a brand new doc for review > easily enough. Perhaps we need to make it easier for someone to > create a new version of an existing doc.... the Iterate diff feature > could make it fairly easy for reviewers to review the changes. > > > > > Personally you can count my contributions out from anything but > > Wiki. I am > > tired with the state of documentation and how hard it to get > > anything fixed > > there. Putting docs to Sphinx besides SVN won't make any good for the > > contribution barrier. > > > > Let's make it a race: doc team can start write its perfect manual > > now and > > meanwhile we just have a wiki, ok? It takes 5 minutes from me or > > Dylan to > > set up a wiki if we can get semiofficial blessing for this with > > having a > > plone.org domain name. developers.plone.org anyone? > > > Why make this into an adversarial thing? It seems to me that the doc > team might possibly be open to the idea of setting up a separate open- > editing sandbox (although I'm personally skeptical about the idea) and > I believe there are some proposals floating that are being taken > seriously. Perhaps it would be more productive to give the doc team > some time to mull the options and actually make a decision before > ratcheting up the rhetoric. :-) > > Peace, > Ric > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win great > prizes > Grand prize is a trip for two to an Open Source event anywhere in the > world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Dylan Jay-4
()
Re: If core code is undocumented it's broken(Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Guy Heckman
Is it possible to ask who in this whole debate actually works at the code
level with Plone? I do every day. Is there anyone who *does* work with code and therefore does need developer documentation, who doesn't like the idea of more open community style docs (wiki) combined perhaps with an official developers manual (also more open to editing)? Who else who *does* work with code, also thinks this idea is worth trying in an "official" way? Dylan Jay Technical Solutions Manager, PretaWeb.com --- M:+61421477460 ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341 > -----Original Message----- > From: Guy Heckman [mailto:[hidden email]] > Sent: Saturday, 22 November 2008 3:21 PM > To: [hidden email] > Subject: Re: [Plone-docs] If core code is undocumented it's > broken(Was:where should developer documentation go?) > > As an implementor and small-time product developer I find a wiki the > way to go. Weblion's wiki solution has served us well over the years > and judging from search results I'm sure more than a few people on > this list have benefitted from it too. My major justification for this > approach is timeliness - I hate having to read down through all of the > comments on a piece of documentation/howto to find what is different > in 3.1 when the original page was written for 2.5 (or any variation > thereof). I think the documentation team is doing a great job but I > have my reservations about the documentation keeping up with the pace > of Plone development, much less maintaining all of the variations > brought about by version changes, in a closed documentation model. My > second argument is more philosophical - why have a closed > documentation process for an open source system? Third and last - many > OS projects have switched to wikis for documentation and it seems to > work, has anyone approached any other OS documentation teams get their > opinion or reasoning for doing what they are doing? > > I do believe that there should be 'official' Plone manuals but I would > think that it could be much more manageable if it drew from an open > and easily accessed/editable centralized source. Let the community do > the submitting & vetting of the materials so the the doc team can > concentrate on form, organization, and presentation. > > > On Nov 21, 2008, at 10:07 PM, Ricardo Newbery wrote: > > > Snip - saving paper ;-) > > > > Guy Heckman > Systems Design Specialist > Programming & Development > Research, Instruction & Information Technology (RIIT) Group > > Smeal College of Business > The Pennsylvania State University > 11 Business Building > University Park, PA 16827 > > Phone: 814-863-9819 > Fax: 814-865-1845 > > http://www.smeal.psu.edu > [hidden email] > > > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's > challenge > Build the coolest Linux based applications with Moblin SDK & win great > prizes > Grand prize is a trip for two to an Open Source event anywhere in the > world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Christopher Warner
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Marco De Vitis
Some javascript/style in this post has been disabled (why?)
I disagree with this.. Primarily because it's people like me who get blocks of time to contribute back to a wiki like setup. So I get a day or two, or thanksgiving vacation to reflect and catchup. I jot down a page, two, more. Even if it's a paragraph it's more than what existed before. What happens now is this when I want to do or find something out about Plone. ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Dylan Jay-4
()
Re: If core code is undocumented it's broken(Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Dylan Jay-4
Please don't take my comments below as a sign that I undervalue the current
effort and previous efforts of the documentation team all the contributors to Plone documentation. I truly believe that the will is there on everyones part both now and in the past and there have been some great examples of developer documentation on Plone.org. It is certainly not a criticism of the effort or ideas of the docteam but it is a frank acknowledgement that the current situation isn't good (no ones fault) and that perhaps we can work smarter not harder. I sincerely hope that others do agree that the developer's documentation story can be improved and we all can all leave our egos by the door, and work together on a consensus on how to move forward on this issue. All I ask is that we be open minded to potentially new and different ways of solving these problems. Dylan Jay Technical Solutions Manager, PretaWeb.com --- M:+61421477460 ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341 > -----Original Message----- > From: Dylan Jay [mailto:[hidden email]] > Sent: Saturday, 22 November 2008 3:22 PM > To: 'Ricardo Newbery'; 'Mikko Ohtamaa' > Cc: [hidden email] > Subject: RE: [Plone-docs] If core code is undocumented it's > broken(Was:where should developer documentation go?) > > I think docs have improved in areas OTHER than developer documentation, > which if anything has got worse as more and more contradictory docs have > been generated. > > I think that developers such as Nikko and myself are getting frustrated > because we see that an incremental approach for developer docs is not > enough. Most of the responses of the doc team seem to be similar to yours > Ricardo. There isn't much of a problem and only tweaks need to be made. > > This situation is all the more urgent because lots of work needs to be > done > to make Plone better and yet it is becoming harder and harder for new > developers to get up to speed on Plone. I know several people personally > who > have tried very hard to use Plone on professional projects and will > probably > now never use Plone again. I've looked at this issue in depth as I have > bet > my business on Plone, and there are other aspects of Plone that will help > Plone be simpler to learn (most of which Martin covered in his talk at the > conference) but developer documentation is still the best bang for our > buck > to improve this situation and still the area where the doc teams seems > think > that nothing is fundamentally wrong. Nothing that extra work from editors > can't fix. > > > > -----Original Message----- > > From: Ricardo Newbery [mailto:[hidden email]] > > Sent: Saturday, 22 November 2008 2:08 PM > > To: Mikko Ohtamaa > > Cc: [hidden email] > > Subject: Re: [Plone-docs] If core code is undocumented it's > > broken(Was:where should developer documentation go?) > > > > > > On Nov 21, 2008, at 5:33 PM, Mikko Ohtamaa wrote: > > > > > To be honest, I don't really believe Plone core community could make > > > any > > > decent output in the traditional way. As we see from the past, this > > > thing > > > has not progressed for several years, besides having email wars @ > > > plone-docs > > > now and then. Doc team doesn't have enough insight and they need to > > > worry > > > about newbies, core team has to worry abouts bugs and technical > > > progress. > > > > > > Again, this is overstating the case. The doc situation has been > > improving steadily for awhile now and the team appears to have plenty > > of productive momentum. IMO, there is still plenty of room for > > improvement but frankly it's not terribly productive (nor fair) to say > > the group lacks insight just because some reasonable concerns are > > expressed about an alternative you are advocating. > > > > > > > > > > >> while people possessing the required expertise can contribute content > > >> anyway if they feel like doing it, regardless of any "to be > > >> written" sign. > > > > > > No they can't contribute. They need to make an plone.org account, > > > log in, > > > read contribution guidelines, fight with the review team and *they > > > can't > > > contribute to existing docs*. That's the trick of Wikipedia - to make > > > contribution barrier so low that it is an attractive opinion to > > > spend your 5 > > > minutes to contribute/polish the little thing. You can either have 5 > > > people > > > writing the documentation or 100 people writing the documentation > > > and 5 > > > people managing it. I don't care if it's disorganized or doesn't > > > satisfy the > > > perfectionism taste of doc team - having something is better than > > > having > > > nothing in this case. Unlike code, manuals don't need "testing" or > > > beta > > > stage - they just need fixing and contributions. Little red links > > > there and > > > here don't matter. > > > > > > The process to contribute to *existing* documents could maybe use some > > improvement. Right now, someone can create a brand new doc for review > > easily enough. Perhaps we need to make it easier for someone to > > create a new version of an existing doc.... the Iterate diff feature > > could make it fairly easy for reviewers to review the changes. > > > > > > > > > Personally you can count my contributions out from anything but > > > Wiki. I am > > > tired with the state of documentation and how hard it to get > > > anything fixed > > > there. Putting docs to Sphinx besides SVN won't make any good for the > > > contribution barrier. > > > > > > Let's make it a race: doc team can start write its perfect manual > > > now and > > > meanwhile we just have a wiki, ok? It takes 5 minutes from me or > > > Dylan to > > > set up a wiki if we can get semiofficial blessing for this with > > > having a > > > plone.org domain name. developers.plone.org anyone? > > > > > > Why make this into an adversarial thing? It seems to me that the doc > > team might possibly be open to the idea of setting up a separate open- > > editing sandbox (although I'm personally skeptical about the idea) and > > I believe there are some proposals floating that are being taken > > seriously. Perhaps it would be more productive to give the doc team > > some time to mull the options and actually make a decision before > > ratcheting up the rhetoric. :-) > > > > Peace, > > Ric > > > > > > ------------------------------------------------------------------------ > - > > This SF.Net email is sponsored by the Moblin Your Move Developer's > > challenge > > Build the coolest Linux based applications with Moblin SDK & win great > > prizes > > Grand prize is a trip for two to an Open Source event anywhere in the > > world > > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > > _______________________________________________ > > Plone-docs mailing list > > [hidden email] > > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Ricardo Newbery-2
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Guy Heckman
I truly hate harping on this but I keep hearing folks conflating issues... wiki != open-editing open-editing != mega-docs There are several distinctly different questions here: 1) Do we want open-editing at all? 2) If we want open-editing, do we want it in a separate sandbox or for all plone.org docs? 3) If we want open-editing, do we want it to be wiki-type or regular plone content-types? 4) Do we want mega-docs? Should they be open-edited? Wiki-type or regular plone content-type? Hopefully, this helps to parse out the pro and con arguments. Ric ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
| Free Embeddable Forum Powered by Nabble | Help |
