Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
| 1 2 3 4 |
|
Dylan Jay-4
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
Thanks for the feedback Christopher.
I couldn't agree more. I'm flicking this over to the doc team to read rather than core developers, as the core developer thread was meant to be more about them saying yes or no regarding it will work with their processes and they will be able to maintain such documentation. my answer to the problems you highlight is we reorganise the docs such that they only appear in one place in a logical section of a logical sequence of a book type structure. And that whole book is versioned a a whole. you would be able to clearly see what the plone2.5 book was vs the plone3 book vs the plone3.2 book. That could be done in plone and it could be done in sphinx. I would say the amount of coding to make plone support cross page versioning would be a lot, although there might be plugins already and if not, its perhaps a worthy cause since it's a problem any large document repository might have. Although you could also do the cheap and nasty way and just copy the entire book to a new folder for each version and then make sure the old versions were marked read only. or you could do it using sphinx and use a system called source control management designed to deal with these exact problems. and at the same time get the benefit of being able to pull in autogenerated api docs where appropriate in examples. Warner, Christopher wrote: > I’m not on core or on the doc team. Sadly, I’ve come to frustration many > times with Plone.org documentation. For instance, just a half an hour > ago I spent time searching for the reference manual on widgets. It’s not > that it’s the most important piece of documentation but it’s probably > something that a developer will refer to often (yeah I should bookmark > it, I know). Beginner or not; that should be an easy link somewhere. > Someone goes to Plone.org then selects documentation and then “Widgets > and Fields” not realizing this isn’t talking about Archetypes Widget > References. Then you have old documentation on Plone 2.x? Backwards > compatibility in documentation is ok; if there is a specific section for > it. Sadly there isn’t. So searching through stuff you get 2.x or 3.x > hopefully it’s labeled. > > Also, I find that more often than not the most useful pieces of > documentation explain a problem and then expose the use of the API. It’s > that or the good stuff is in sections you wouldn’t really think about. > For instance the discussion of component wiring and zcml? It’s under > themes and then there is a link to a tutorial on worldcookery.com about > ZCML and then an explanation of five. This; under themes?? > > How do I use the workflow tool? > Actually, what are all these tools about and how do I use them? > How do I use all this cool event system stuff? > Why would I want to use browser views instead of skins? > What in the hell is ZCML? > Forms have worked for a while now with straight html? Why would I want > to write python code for a form? > > These are just all questions but there is nothing that steps you through > from one area to the next. Then there is the confusing Plone 2 + Plone 3 > = Five subsystem. I’m not even sure where to begin explaining this to > someone who has just decided to start using Plone far less develop for it. > > Anyway what I’m saying is that in my own opinion there needs to be a > soup to nuts walk through guide, the api doc; even if it uses sphinx > needs examples on how it relates to real world problems and the > organization and structure need to be thought out. Finally many add-on > products provide extremely poor examples or just reference the code. > Good for me and you, for a new developer; not as good, so maybe the doc > team should be vetting this before a product hits the collective or > plone.org. If a new developer or new user can’t understand it by reading > something comprehensive; it is broken. > > -- > 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/15/08 5:39 PM, "Dylan Jay" > <[hidden email]> wrote: > > Ricardo Newbery wrote: > > On Nov 15, 2008, at 5:22 AM, Dylan Jay wrote: > > > > > > I'm sick of all this debate, we won't know till we try it and see. > > > > I agree. I for one am very eager to try it out.... for add-on product > > documentation. :-) > > add-on products are already covered by rst documentation in the form of > readmes on pypi and I believe with the great work tarek has been doing > to update the PSC it will also be like a pypi and be able to rull in > code based docs. > > So none of this is about sphinx for addons, its about sphinx for "core" > code. > We've already shown that maintaining code code documentation so far away > from the development processes and tools has failed. And been maintained > by docteam who aren't core developers has failed. > > Iie updating the core code documentation to plips. Tie it to the plone > release process. Make anyone submitting new core code have to review the > manual for impact of their changes. > > If core code is undocmented its broken. > I would go further and say if core code can't fit nicely into a > narrative explanation of the plone core code, it's probably broken too. > Our api is our story and if its a story few can follow then we are > losing audience. > > It's a new idea. it might just work. but it does require core team > buy in. > The idea was to get the core development teams comments not the > docteams. > > > > > > ------------------------------------------------------------------------- > 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=/ > <http://moblin-contest.org/redirect.php?banner_id=100&url=/> > _______________________________________________ > Plone-developers mailing list > [hidden email] > <[hidden email]> > https://lists.sourceforge.net/lists/listinfo/plone-developers > > > ------------------------------------------------------------------------ > > ------------------------------------------------------------------------- > 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-developers mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-developers ------------------------------------------------------------------------- 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?)
|
|
||||||||||||
|
The current documentation situation is much improved from its previous incarnations and it seems like the doc team is well on the way to improving it still more. That being said, I agree we still have problems. It should be easier to find some bits. It should be easier to filter out the bits that aren't relevant. There are too many mini docs of marginal utility that interfere with efficient navigation. IMHO, the problem isn't whether we need to choose between one mega- document to walk through *all* of Plone or a bunch of discrete documents covering specific topics. Whether we have one doc or many, what we need is an information architecture and navigation that makes it easier to find the bits you need and filter out the bits you don't. There is nothing intrinsic to maintaining mega-docs that would make them more usable or accurate than maintaining discrete medium-size docs. There is also nothing intrinsic to maintaining mega-docs that would help encourage and empower contributers more than maintaining discrete medium-size docs. On the other hand, a mega-doc may tend to encourage a single vision of focus, presentation, and style. That may be a good thing... or it may not. I'm not sure. Perhaps also there is some benefit to organizing documentation by Plone version, or perhaps just make it easier to navigate or filter documentation by Plone version. Ric On Nov 17, 2008, at 3:17 PM, Dylan Jay wrote: > Thanks for the feedback Christopher. > > I couldn't agree more. > > I'm flicking this over to the doc team to read rather than core > developers, as the core developer thread was meant to be more about > them > saying yes or no regarding it will work with their processes and they > will be able to maintain such documentation. > > my answer to the problems you highlight is we reorganise the docs such > that they only appear in one place in a logical section of a logical > sequence of a book type structure. And that whole book is versioned > a a > whole. you would be able to clearly see what the plone2.5 book was vs > the plone3 book vs the plone3.2 book. > > That could be done in plone and it could be done in sphinx. > I would say the amount of coding to make plone support cross page > versioning would be a lot, although there might be plugins already and > if not, its perhaps a worthy cause since it's a problem any large > document repository might have. > > Although you could also do the cheap and nasty way and just copy the > entire book to a new folder for each version and then make sure the > old > versions were marked read only. > > or you could do it using sphinx and use a system called source control > management designed to deal with these exact problems. and at the same > time get the benefit of being able to pull in autogenerated api docs > where appropriate in examples. > > > Warner, Christopher wrote: >> I’m not on core or on the doc team. Sadly, I’ve come to frustration >> many >> times with Plone.org documentation. For instance, just a half an hour >> ago I spent time searching for the reference manual on widgets. >> It’s not >> that it’s the most important piece of documentation but it’s probably >> something that a developer will refer to often (yeah I should >> bookmark >> it, I know). Beginner or not; that should be an easy link somewhere. >> Someone goes to Plone.org then selects documentation and then >> “Widgets >> and Fields” not realizing this isn’t talking about Archetypes Widget >> References. Then you have old documentation on Plone 2.x? Backwards >> compatibility in documentation is ok; if there is a specific >> section for >> it. Sadly there isn’t. So searching through stuff you get 2.x or 3.x >> hopefully it’s labeled. >> >> Also, I find that more often than not the most useful pieces of >> documentation explain a problem and then expose the use of the API. >> It’s >> that or the good stuff is in sections you wouldn’t really think >> about. >> For instance the discussion of component wiring and zcml? It’s under >> themes and then there is a link to a tutorial on worldcookery.com >> about >> ZCML and then an explanation of five. This; under themes?? >> >> How do I use the workflow tool? >> Actually, what are all these tools about and how do I use them? >> How do I use all this cool event system stuff? >> Why would I want to use browser views instead of skins? >> What in the hell is ZCML? >> Forms have worked for a while now with straight html? Why would I >> want >> to write python code for a form? >> >> These are just all questions but there is nothing that steps you >> through >> from one area to the next. Then there is the confusing Plone 2 + >> Plone 3 >> = Five subsystem. I’m not even sure where to begin explaining this to >> someone who has just decided to start using Plone far less develop >> for it. >> >> Anyway what I’m saying is that in my own opinion there needs to be a >> soup to nuts walk through guide, the api doc; even if it uses sphinx >> needs examples on how it relates to real world problems and the >> organization and structure need to be thought out. Finally many add- >> on >> products provide extremely poor examples or just reference the code. >> Good for me and you, for a new developer; not as good, so maybe the >> doc >> team should be vetting this before a product hits the collective or >> plone.org. If a new developer or new user can’t understand it by >> reading >> something comprehensive; it is broken. >> >> -- >> 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/15/08 5:39 PM, "Dylan Jay" >> <[hidden email]> wrote: >> >> Ricardo Newbery wrote: >>> On Nov 15, 2008, at 5:22 AM, Dylan Jay wrote: >> >>> >>>> I'm sick of all this debate, we won't know till we try it and see. >>> >>> I agree. I for one am very eager to try it out.... for add-on >>> product >>> documentation. :-) >> >> add-on products are already covered by rst documentation in the >> form of >> readmes on pypi and I believe with the great work tarek has been >> doing >> to update the PSC it will also be like a pypi and be able to >> rull in >> code based docs. >> >> So none of this is about sphinx for addons, its about sphinx for >> "core" >> code. >> We've already shown that maintaining code code documentation so >> far away >> from the development processes and tools has failed. And been >> maintained >> by docteam who aren't core developers has failed. >> >> Iie updating the core code documentation to plips. Tie it to the >> plone >> release process. Make anyone submitting new core code have to >> review the >> manual for impact of their changes. >> >> If core code is undocmented its broken. >> I would go further and say if core code can't fit nicely into a >> narrative explanation of the plone core code, it's probably >> broken too. >> Our api is our story and if its a story few can follow then we are >> losing audience. >> >> It's a new idea. it might just work. but it does require core team >> buy in. >> The idea was to get the core development teams comments not the >> docteams. >> >> >> >> >> >> >> ------------------------------------------------------------------------- >> 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=/ >> <http://moblin-contest.org/redirect.php?banner_id=100&url=/> >> _______________________________________________ >> Plone-developers mailing list >> [hidden email] >> <[hidden email] >> > >> https://lists.sourceforge.net/lists/listinfo/plone-developers >> >> >> ------------------------------------------------------------------------ >> >> ------------------------------------------------------------------------- >> 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-developers mailing list >> [hidden email] >> https://lists.sourceforge.net/lists/listinfo/plone-developers > > > ------------------------------------------------------------------------- > 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 |
||||||||||||||
|
Israel Saeta Pérez
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
I'm really happy to see sooo many new discussions being hold about
plone.org documentation organization and management. This list looks more full of life than ever. :-) Warner, yes, maybe we should try to keep an authoritative set of docs explaining how do you do X with Plone x.y. I'm in favour of focusing on problem solving by topic rather than describing a module interface since I believe it is more useful to newcomers, and no so newcomers; e.g. "Forms and widgets" instead of "How to use zope.formlib". Of course we also need module documentation, including api docs, and I'm sure sphinx can help us a lot here. Thanks garbas! Some sections of the Plone machinery are sorely lack of good documentation - please help us to identify the holes and find people/time to fill them. Co-editors are welcomed, specially in the development section, which is huge. Ricardo, we can write small documents about each topic and use hyperlinks. ;-) IMHO plone.org "official" (is this the way we're gearing towards?) documentation should enforce a single vision to avoid confusion; it should be coherent. Keep up the good discussion! -- israel ------------------------------------------------------------------------- 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 Israel Saeta Pérez
|
||||||||||||||
|
|
Israel Saeta Pérez
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
btw, Christopher, I loved the "if the code is undocumented, it's
broken" motto. :-) -- israel ------------------------------------------------------------------------- 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 Israel Saeta Pérez
|
||||||||||||||
|
JoAnna Springsteen
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
On Mon, Nov 17, 2008 at 7:19 PM, Israel Saeta Pérez <[hidden email]> wrote:
> btw, Christopher, I loved the "if the code is undocumented, it's > broken" motto. :-) > think we can get the framework team to adopt it? ;) ------------------------------------------------------------------------- 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 Dylan Jay-4
Christopher, If I understand you correctly, it seems you are arguing for better written and more relevant documentation. I don't think anyone here would disagree. I agree that the problem is not all just one of organization and navigability. We have some really good docs. We also have some not so good. I'm pretty sure the doc team is aware of this and are working on it. And I'm sure they would appreciate any specific examples of problems you see. But that being said, the example you did cite confuses me... http://plone.org/documentation/tutorial/where-is-what/the-logo/?searchterm=change%20plone%20logo To my eye this doc doesn't seem too bad. I think I might have written it a little differently -- it's a little too terse; you really shouldn't assume that people have read the prior pages in a multipage document; the steps required to do something should be an ordered list not an unordered list; and perhaps an example should be included -- but other than that, it's actually not too bad. If you have suggestions on how to improve this doc, I'm sure the doc team would be happy to hear it. But... is the complaint that the steps to change the plone logo are a little cumbersome? I agree. Simple theming changes should be easier. The current situation is a little like needing to take your car to the mechanic just to change the seat covers. But that's not really a documentation issue, it's a code issue. Ric On Nov 18, 2008, at 9:15 AM, Warner, Christopher wrote: > I tend to agree, however you can’t navigate efficiently what isn’t > there or if it’s become a tangled mess it needs to be untangled. As > a user of Plone, developer, and general advocate of it as the > enterprise CMS of choice. It all seems like a tangled mess to me. > It’s embarrassing for me to say to people, “Go to plone.org and read > X introduction tutorial.”, because really it’s an exercise in > frustration for new comers. Justifying it at work has only been > possible because the people in-charge believe I have a slight idea > as to what I’m talking about. How come I can’t say to management, > peers, or just a random individual interested in what I’m talking > about; Here’s an overview of this Enterprise CMS. These are the > things it offers and here is a high level overview of all the pieces > and how they fit together. Here’s a decent manual if you are > interested. Here’s a system administrator overview; it’s not a LAMP > stack so we need a manual/section for that. Etc etc. It’s > intimidating for new users! > > It’s sort of like this weekend, my own cousin, who’s a rocket > scientist sits in front of my computer. She says, “How do I eject > the cdrom?” I say, “Press the eject key.” She pressed it but didn’t > hold it down. So it didn’t eject. She then whined about how it > doesn’t work, even though she has her own macbook pro she never used > a tower before so it seemed foreign. The problem wasn’t that it > didn’t work; it was my instruction. When I told her to hold down the > eject button; it made perfect sense to her. > > So the “Press the eject button” and “Press and hold the eject > button”. Made all the difference, summarily that’s what I feel is > missing we also now know it takes one rocket scientist to press an > eject key. Kidding aside, that extra piece that can make things > clear. A mega-doc can always be cut into little more useful chapters > or pieces once it’s organized correctly. If we can start with > something along the lines of What is the first thing a person may > want to do when they’ve installed Plone? Change the logo? Change the > theme? Etc. This can lead into more advanced and comprehensively > more difficult topics slowly. The developer and documentation team > absolutely need to work together for this to happen. > > Lets take a look at what I find when I search for “Change plone logo” > http://plone.org/documentation/tutorial/where-is-what/the-logo/?searchterm=change%20plone%20logo > > I’m not debating the validity of the instruction, however I can’t > honestly tell someone who’s interested in Plone and wants to change > their logo to read this page. Far less the default theme. Its just > useless to them. It’s hard to sell this stuff when people can’t > understand it and the documentation doesn’t make it easy; for > anyone. I really want to attack this problem head-on because it’s > the #1 problem opensource products always have. Zope/Plone get a bad > rap because you need to be dedicated and an excellent programmer to > get anything done. The world is filled with Drupal and Wordpress and > all that because they make it easy, not because it’s better but > because it’s accessible. Not everyone is dedicated or excellent at > what they do, the world is filled with mediocre; there’s nothing > wrong with that but we are all mediocre at something. http://drupal.org/files/getting-started_2.pdf > <- How come we don’t have this? It’s not like we can’t do it.. > > Yesterday, I had to send out yet another email saying “Plone is > great... This maybe hard... Don’t be scared...”. I like hard > problems, so for me that may actually get me interested; but > everyone else wants to do their job, go home and play some pool. I > can understand that. > > -- > 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/17/08 7:28 PM, "Ricardo Newbery" <[hidden email]> wrote: > >> >> >> >> The current documentation situation is much improved from its >> previous >> incarnations and it seems like the doc team is well on the way to >> improving it still more. That being said, I agree we still have >> problems. It should be easier to find some bits. It should be >> easier >> to filter out the bits that aren't relevant. There are too many mini >> docs of marginal utility that interfere with efficient navigation. >> >> IMHO, the problem isn't whether we need to choose between one mega- >> document to walk through *all* of Plone or a bunch of discrete >> documents covering specific topics. Whether we have one doc or many, >> what we need is an information architecture and navigation that makes >> it easier to find the bits you need and filter out the bits you >> don't. >> >> There is nothing intrinsic to maintaining mega-docs that would make >> them more usable or accurate than maintaining discrete medium-size >> docs. There is also nothing intrinsic to maintaining mega-docs that >> would help encourage and empower contributers more than maintaining >> discrete medium-size docs. >> >> On the other hand, a mega-doc may tend to encourage a single vision >> of >> focus, presentation, and style. That may be a good thing... or it >> may >> not. I'm not sure. >> >> Perhaps also there is some benefit to organizing documentation by >> Plone version, or perhaps just make it easier to navigate or filter >> documentation by Plone version. >> >> 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 |
||||||||||||||
|
vedaw
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
Hi Christopher,
Since you mention this particular example ( http://plone.org/documentation/tutorial/where-is-what/the-logo/?searchterm=c hange%20plone%20logo), I'd like to point out that in the last two weeks, Anne Bowtell has been busily writing a proper "how do I change my logo" document that should make it a little more findable and relevant. Anne is also the person who wrote the awesome theming manual that we now have. In the last couple of days, I've hidden 20 or so outdated docs in the theming area, and added a "start here" document from Trey Beck here: http://plone.org/documentation/how-to/how-to-create-a-plone-3-theme-product- on-the-filesystem Also, I added a new document about putting your site in debug mode, using (IIRC) something from John DeStefano's document: http://plone.org/documentation/how-to/how-to-make-your-css-changes-take-effe ct-instantly I didn't change it much from the original, I just surfaced it higher so that new users don't have to dig to find it. Not only that, I'm in the middle of writing a theming book for Plone, and helping to get the new Practical Plone book out the door as well (not to mention writing two chapters for it): http://packtpub.com/building-plone-websites-through-the-graphical-interface/ book I appreciate that you're telling us that you think the documentation is insufficient, and we hear you. My feeling is that if you see something and you know it's broken, help fix it. Anne and I are only two people, trying to make the most of the time we have, and quite frankly I'm exhausted. And I'm just speaking for the theming section of plone.org/documentation. While you feel bad saying you don't want to send out an email saying, ³Plone is great... This maybe hard... Don¹t be scared...,² I don't want to have to send out an email that says I'm too burned out to participate anymore because no one else wanted to actually write the documentation. The upshot? Get involved. Write. Submit. We need the help, and I'd like a day off. - Veda > > On Nov 18, 2008, at 9:15 AM, Warner, Christopher wrote: > >> I tend to agree, however you can¹t navigate efficiently what isn¹t >> there or if it¹s become a tangled mess it needs to be untangled. As >> a user of Plone, developer, and general advocate of it as the >> enterprise CMS of choice. It all seems like a tangled mess to me. >> It¹s embarrassing for me to say to people, ³Go to plone.org and read >> X introduction tutorial.², because really it¹s an exercise in >> frustration for new comers. Justifying it at work has only been >> possible because the people in-charge believe I have a slight idea >> as to what I¹m talking about. How come I can¹t say to management, >> peers, or just a random individual interested in what I¹m talking >> about; Here¹s an overview of this Enterprise CMS. These are the >> things it offers and here is a high level overview of all the pieces >> and how they fit together. Here¹s a decent manual if you are >> interested. Here¹s a system administrator overview; it¹s not a LAMP >> stack so we need a manual/section for that. Etc etc. It¹s >> intimidating for new users! >> >> It¹s sort of like this weekend, my own cousin, who¹s a rocket >> scientist sits in front of my computer. She says, ³How do I eject >> the cdrom?² I say, ³Press the eject key.² She pressed it but didn¹t >> hold it down. So it didn¹t eject. She then whined about how it >> doesn¹t work, even though she has her own macbook pro she never used >> a tower before so it seemed foreign. The problem wasn¹t that it >> didn¹t work; it was my instruction. When I told her to hold down the >> eject button; it made perfect sense to her. >> >> So the ³Press the eject button² and ³Press and hold the eject >> button². Made all the difference, summarily that¹s what I feel is >> missing we also now know it takes one rocket scientist to press an >> eject key. Kidding aside, that extra piece that can make things >> clear. A mega-doc can always be cut into little more useful chapters >> or pieces once it¹s organized correctly. If we can start with >> something along the lines of What is the first thing a person may >> want to do when they¹ve installed Plone? Change the logo? Change the >> theme? Etc. This can lead into more advanced and comprehensively >> more difficult topics slowly. The developer and documentation team >> absolutely need to work together for this to happen. >> >> Lets take a look at what I find when I search for ³Change plone logo² >> http://plone.org/documentation/tutorial/where-is-what/the-logo/?searchterm=ch >> ange%20plone%20logo >> >> I¹m not debating the validity of the instruction, however I can¹t >> honestly tell someone who¹s interested in Plone and wants to change >> their logo to read this page. Far less the default theme. Its just >> useless to them. It¹s hard to sell this stuff when people can¹t >> understand it and the documentation doesn¹t make it easy; for >> anyone. I really want to attack this problem head-on because it¹s >> the #1 problem opensource products always have. Zope/Plone get a bad >> rap because you need to be dedicated and an excellent programmer to >> get anything done. The world is filled with Drupal and Wordpress and >> all that because they make it easy, not because it¹s better but >> because it¹s accessible. Not everyone is dedicated or excellent at >> what they do, the world is filled with mediocre; there¹s nothing >> wrong with that but we are all mediocre at something. >> http://drupal.org/files/getting-started_2.pdf >> <- How come we don¹t have this? It¹s not like we can¹t do it.. >> >> Yesterday, I had to send out yet another email saying ³Plone is >> great... This maybe hard... Don¹t be scared...². I like hard >> problems, so for me that may actually get me interested; but >> everyone else wants to do their job, go home and play some pool. I >> can understand that. >> >> -- >> 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/17/08 7:28 PM, "Ricardo Newbery" <[hidden email]> wrote: >> >>> >>> >>> >>> The current documentation situation is much improved from its >>> previous >>> incarnations and it seems like the doc team is well on the way to >>> improving it still more. That being said, I agree we still have >>> problems. It should be easier to find some bits. It should be >>> easier >>> to filter out the bits that aren't relevant. There are too many mini >>> docs of marginal utility that interfere with efficient navigation. >>> >>> IMHO, the problem isn't whether we need to choose between one mega- >>> document to walk through *all* of Plone or a bunch of discrete >>> documents covering specific topics. Whether we have one doc or many, >>> what we need is an information architecture and navigation that makes >>> it easier to find the bits you need and filter out the bits you >>> don't. >>> >>> There is nothing intrinsic to maintaining mega-docs that would make >>> them more usable or accurate than maintaining discrete medium-size >>> docs. There is also nothing intrinsic to maintaining mega-docs that >>> would help encourage and empower contributers more than maintaining >>> discrete medium-size docs. >>> >>> On the other hand, a mega-doc may tend to encourage a single vision >>> of >>> focus, presentation, and style. That may be a good thing... or it >>> may >>> not. I'm not sure. >>> >>> Perhaps also there is some benefit to organizing documentation by >>> Plone version, or perhaps just make it easier to navigate or filter >>> documentation by Plone version. >>> >>> 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 |
||||||||||||||
|
Christopher Warner
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by Ricardo Newbery-2
Some javascript/style in this post has been disabled (why?)
So how could the document on changing the logo be more accessible? Changing the logo via Zope Management Interface (ZMI):
Etc. The idea is to make the easy things; easy by simply guiding the user through a series of steps to reach an end goal. As you move them along the steps you can explain and expose more advanced topics where it makes sense. So for instance after this it maybe an interesting time to talk about theming or changing the css layout. Plone 2.x vs Plone 3.x a new user doesn’t care. The documentation should reflect one or the other version. Notice at the end of the document Shaun Roe put a “Idiot’s Guide”. That one paragraph is more accessible than the current documentation. That said I’m not debating its validity; it’s clearly readable to someone like me or you but so is the Idiot’s Guide. So, Shaun obviously got to the document by searching just like a new user would for “Change Plone Logo” found this document; was confused, figured it out. Posted about it and then was told about something he probably had completely no idea about, portal_view_customizations. This is from April 27, 2008... -- 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/18/08 2:28 PM, "Ricardo Newbery" <ric@...> wrote: Christopher, ------------------------------------------------------------------------- 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?)
http://plone.org/documentation/how-to/change-the-logo-in-plone-3 Anne will look at your other comments and address them or incorporate them, as needed. Portal_view_customizations is yet another way to change the logo, and she and I need to talk about how to handle that, since it’s kind of a weird animal and is hard to get stuff from there to the filesystem. This is more of a programmatic issue, but we still have to address it. Thanks! - Veda On 11/18/08 1:01 PM, "Warner, Christopher" <[hidden email]> wrote: Yes, I’m arguing for not just better documentation by itself but cohesive and accessible documentation. If I am a new user and I search for “Change Plone Logo” the first thing that comes up as a match is that link. So as a new user I will click that link and be absolutely confused. If I’m smart enough to go to Page 1 it’s still not going to help me. Then towards the bottom is a broken link; so the how-to is missing. ------------------------------------------------------------------------- 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?)
Off the top of my head there are at least 4 different areas where documentation is severely lacking. A very high level introduction. A framework section, explaining how to use the API. A users-guide. A system administrator guide. And random one-off documents like. “Plone for your Manager” etc etc. If there is a way to have general consensus on this and get everyone together that would be sweet. It’s clearly not a one man job; that said I’m willing to help in whatever manner you’d have me if we accomplish even 10% of the above. -- 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/18/08 3:28 PM, "Veda Williams" <veda@...> wrote: Hi Christopher, ------------------------------------------------------------------------- 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?)
Agreed, there are some real problem areas here. We have a couple of things happening right now that might interest you. 1) Israel Saeta Perez is working on a step-by-step document that walks people through the natural course of action they’d need to follow when using Plone: how to install, how to find help, how to install add on products, how to use buildout, how to host. This doc is intended to just link out to other docs. I’m sure Israel (dukebody) could use some help here, ‘cause it’s a big one: http://plone.org/documentation/tutorial/getting-started-with-plone (if you need rights to read it, let me know and I’ll set you up). If this interests you, please speak up and Israel will coordinate with you. 2) I’d be curious to know what you have to add to the Users Guide: http://plone.org/documentation/manual/plone-3-user-manual Joanna, Sam Knox and a few others can probably help coordinate on this one. There’s another doc involved here, which is a “new to plone” document that would be featured prominently on the home page of plone.org/documentation. Sam did a first pass at this, but it could probably use some work. This is where I see “Plone for your manager” fitting, btw. 3) Along these lines, I myself would like to see some updates happen to this doc to make it a bit friendlier. Perhaps you would be willing to tackle this, or simply review the doc and communicate those comments to John DeRosa and see if he can make the updates? http://plone.org/documentation/tutorial/where-is-what/ 4) System Administrators Guide. You are 100% right that we don’t have anything like this, and if you want to lead this project (or someone else volunteers to lead it), feel free. 5) If none of that appeals to you, the editors are all working on their section assessments, listed here, to point out additional areas where we need to improve: http://www.openplans.org/projects/plone-documentation/project-home Basically, it’s up to you to choose which area you think would be a good fit for you, and we’ll connect you with the editor who can help make it happen. If you want to brainstorm, review, or even write, we’re happy for the help. Just let us know where you see yourself fitting, and we’ll connect you with the right editor. Thanks! Veda PS, the irony is that I swore I’d never be a documentation person, but it’s funny how it finds you when your own itch isn’t being scratched. :) On 11/18/08 1:13 PM, "Warner, Christopher" <[hidden email]> wrote: Thanks for your efforts Veda. Genuinely. I realize documentation is not the most fun or easy thing to do especially as a volunteer and you have my utmost respect and sympathies for your work thus far. I do plan to roll up my sleeves and get dirty as well I just think it would be much easier for people to contribute if there was a clear direction and outline of what the project wants to accomplish. I’m only making this plea because selfishly I want to promote Plone and this is a severe road-block for me doing so. ------------------------------------------------------------------------- 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?)
|
|
||||||||||||
|
In reply to this post
by Christopher Warner
On Tue, Nov 18, 2008 at 3:13 PM, Warner, Christopher
<[hidden email]> wrote: > Thanks for your efforts Veda. Genuinely. I realize documentation is not the > most fun or easy thing to do especially as a volunteer and you have my > utmost respect and sympathies for your work thus far. I do plan to roll up > my sleeves and get dirty as well I just think it would be much easier for > people to contribute if there was a clear direction and outline of what the > project wants to accomplish. I'm only making this plea because selfishly I > want to promote Plone and this is a severe road-block for me doing so. Actually, we do have a plan. http://www.openplans.org/projects/plone-documentation/doc-team-roadmap We've figured out what our goals are...we're just in the process of figuring out how we're going to accomplish/implement them. I highly suggest that anyone who wants to be involved read and know this roadmap. This is what we are operating from. > Off the top of my head there are at least 4 different areas where > documentation is severely lacking. > > A very high level introduction. working on it. Israel has a great draft of a New to Plone doc. Should go live when plone.org switches over to 3.x. > A framework section, explaining how to use the API. from what I understand API is being updated using sphinx. > A users-guide. Have it for 2.5 and 3.x. Sam Knox has recently proposed more improvements. > A system administrator guide. I think we have bits and pieces but nothing too cohesive. I know everyone thinks we're really bad off, but we aren't as bad as you think. We are making progress. ------------------------------------------------------------------------- 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 |
||||||||||||||
|
Anne Bowtell
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by vedaw
I'll look at this all this weekend, which is when I've set aside some
time to do a bit more on the theming docs - with particular focus on gardening the logo docs. Like Veda, I'm a bit overwhelmed at the moment (though in my case its the day job taking over my life), so progress has been slow. It is really helpful to have these comments - thank you. Theming for Plone 3 is complicated (too complicated) and it is difficult to make the instructions simple when the process actually isn't. So the feedback is useful on all sorts of levels. I'd also like to thank Veda for everything she's doing right now. Not only is she working really hard to get these publications out the door, but she's also taking time to read over and comment on what I'm doing - support I appreciate very much indeed. Please join us, we've got a list of things we'd like to get done. Anne Veda Williams wrote: > I just spotted the broken link and fixed it to point to this tutorial: > > http://plone.org/documentation/how-to/change-the-logo-in-plone-3 > > Anne will look at your other comments and address them or incorporate > them, as needed. Portal_view_customizations is yet another way to change > the logo, and she and I need to talk about how to handle that, since > it’s kind of a weird animal and is hard to get stuff from there to the > filesystem. This is more of a programmatic issue, but we still have to > address it. > > Thanks! > > - Veda > > > On 11/18/08 1:01 PM, "Warner, Christopher" > <[hidden email]> wrote: > > Yes, I’m arguing for not just better documentation by itself but > cohesive and accessible documentation. If I am a new user and I > search for “Change Plone Logo” the first thing that comes up as a > match is that link. So as a new user I will click that link and be > absolutely confused. If I’m smart enough to go to Page 1 it’s still > not going to help me. Then towards the bottom is a broken link; so > the how-to is missing. > > > So how could the document on changing the logo be more accessible? > > Changing the logo via Zope Management Interface (ZMI): > > 1. Access the Zope Management Interface which is used to control > Plone. You can do this by going to > http://localhost:8080/Plone/manage (or replace localhost with > your own proper domain and port) > 2. In the left frame panel there is a tool called “portal_skins” > (highlighted; link to definition of portal_skins and what it > means. Portal_skins is a tool that manages all of the related > visual aspects of Plone) it looks like <image here of the > portal skins icon> and is located in the left-hand pane. > Select “portal_skins” from the list. > 3. In the right pane a list of skin related directories should be > displayed. All of these directories are associated with what > we see displayed in Plone from the front page to the > administrative interface. However, for what we want to do > right now, the one we are interested in is “custom”. > (highlighted: link to definition, It is named custom because > it allows us to override and modify the look of the default > Plone skin) > 4. If things are going well in the Right pane you should see the > below: (IMAGE_HERE) the folder custom currently has nothing in > it. > 5. Have the logo you plan to replace ready, based on the default > theme a logo of XYZ image scale would be appropriate. > > > Etc. > > The idea is to make the easy things; easy by simply guiding the user > through a series of steps to reach an end goal. As you move them > along the steps you can explain and expose more advanced topics > where it makes sense. So for instance after this it maybe an > interesting time to talk about theming or changing the css layout. > Plone 2.x vs Plone 3.x a new user doesn’t care. The documentation > should reflect one or the other version. > > Notice at the end of the document Shaun Roe put a “Idiot’s Guide”. > That one paragraph is more accessible than the current > documentation. That said I’m not debating its validity; it’s clearly > readable to someone like me or you but so is the Idiot’s Guide. > > So, Shaun obviously got to the document by searching just like a new > user would for “Change Plone Logo” found this document; was > confused, figured it out. Posted about it and then was told about > something he probably had completely no idea about, > portal_view_customizations. > > This is from April 27, 2008... > > > > ------------------------------------------------------------------------ > > ------------------------------------------------------------------------- > 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 |
||||||||||||||
|
|
vedaw
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by JoAnna Springsteen
>> >> A very high level introduction. > > working on it. Israel has a great draft of a New to Plone doc. Should > go live when plone.org switches over to 3.x. Based on what's on plone.org now, it looks like it has a long way to go. This one will likely be a community effort, and I'm tossing my name out there to work on the theming section for this. There are other areas where he could probably use the help. >> A framework section, explaining how to use the API. > > from what I understand API is being updated using sphinx. Still in discussion... > I know everyone thinks we're really bad off, but we aren't as bad as > you think. We are making progress. Yep, but any help is welcome. ------------------------------------------------------------------------- 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 JoAnna Springsteen
> -----Original Message-----
> From: JoAnna Springsteen [mailto:[hidden email]] > Sent: Wednesday, 19 November 2008 8:28 AM > To: Warner, Christopher > Cc: [hidden email] > Subject: Re: [Plone-docs] If core code is undocumented it's broken > (Was:where should developer documentation go?) > > On Tue, Nov 18, 2008 at 3:13 PM, Warner, Christopher > <[hidden email]> wrote: > > Thanks for your efforts Veda. Genuinely. I realize documentation is not > the > > most fun or easy thing to do especially as a volunteer and you have my > > utmost respect and sympathies for your work thus far. I do plan to roll > up > > my sleeves and get dirty as well I just think it would be much easier > for > > people to contribute if there was a clear direction and outline of what > the > > project wants to accomplish. I'm only making this plea because selfishly > I > > want to promote Plone and this is a severe road-block for me doing so. > > > > Actually, we do have a plan. > http://www.openplans.org/projects/plone-documentation/doc-team-roadmap > > We've figured out what our goals are...we're just in the process of > figuring out how we're going to accomplish/implement them. It certainly helps to know what how and who is going to implement them in order to get support of those that can help. One thing we could do better is clearly demonstrate where the holes are instead of it all going on behind closed doors and assuming the wider Plone community is aware of them. 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. > I highly suggest that anyone who wants to be involved read and know > this roadmap. This is what we are operating from. > > > > Off the top of my head there are at least 4 different areas where > > documentation is severely lacking. > > > > A very high level introduction. > > working on it. Israel has a great draft of a New to Plone doc. Should > go live when plone.org switches over to 3.x. > > > > A framework section, explaining how to use the API. > > from what I understand API is being updated using sphinx. > > > A users-guide. > > Have it for 2.5 and 3.x. Sam Knox has recently proposed more improvements. > > > A system administrator guide. > > I think we have bits and pieces but nothing too cohesive. > > > I know everyone thinks we're really bad off, but we aren't as bad as > you think. We are making progress. > > ------------------------------------------------------------------------- > 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 |
||||||||||||||
|
|
JoAnna Springsteen
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
> It certainly helps to know what how and who is going to implement them in
> order to get support of those that can help. As of right now, most of this falls on the editors shoulders. One of the editors main responsibilities is recruiting help for their sections and any tasks associated with their sections. But yes, we do still need to work on assigning tasks. Right now everyone is focusing on their assessments, which are due at the end of 2008. Once that deadline has been met, we move on to other tasks that will be more visible. > One thing we could do better is clearly demonstrate where the holes are > instead of it all going on behind closed doors and assuming the wider Plone > community is aware of them. This is the goal and entire purpose of posting our doc section assessments Right on the front page of the wiki: http://www.openplans.org/projects/plone-documentation/project-home Each editor has given each doc a rating, posted comments, and some have even gotten to the point where they are filling the gaps (see Veda's recent email on docs published). It's all there, out in the open, for the whole community to see. You don't even need to be a member of the doc project on open plans to see any of it. We can only show you where it is...we can't force you to read it. > 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. uh, why would we not have the doc team implement the documentation team roadmap? We have a huge amount of members. It's just that only a handful of people consistently step up and participate. We're not some exclusive club here. If you're on the mailing list you're considered part of the doc team. If everyone who subscribes to this list chipped in just an hour or so of time, we could easily whip this doc section into shape. Unfortunately, that's not the case. We're doing the best with the volunteers and the time they have. ------------------------------------------------------------------------- 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?)
|
|
||||||||||||
|
Sorry I'm obviously a shocking communicator because my entire point missed
you completely. We could do what argo and has done http://argouml-stats.tigris.org/documentation/manual-0.26/ 1. create the structure 2. publish with empty holes - in a place where users expect to see real documentation. 3. watch as a wave of contributions come in. "hey the working with workflow section is yet to be written, I think I can write that, oh look, theres a link for someone to email...." 4. move/delete all the old docs out of the way into a less official area. Dylan Jay Technical Solutions Manager, PretaWeb.com --- M:+61421477460 ~ MSN:[hidden email] ~ Y!+Skype:dylan_jay ~ ICQ:520341 > -----Original Message----- > From: JoAnna Springsteen [mailto:[hidden email]] > Sent: Wednesday, 19 November 2008 2:49 PM > To: Dylan Jay > Cc: [hidden email]; Warner, Christopher > Subject: Re: [Plone-docs] If core code is undocumented it's broken > (Was:where should developer documentation go?) > > > It certainly helps to know what how and who is going to implement them > in > > order to get support of those that can help. > > As of right now, most of this falls on the editors shoulders. One of > the editors main responsibilities is recruiting help for their > sections and any tasks associated with their sections. But yes, we do > still need to work on assigning tasks. Right now everyone is focusing > on their assessments, which are due at the end of 2008. Once that > deadline has been met, we move on to other tasks that will be more > visible. > > > One thing we could do better is clearly demonstrate where the holes are > > instead of it all going on behind closed doors and assuming the wider > Plone > > community is aware of them. > > This is the goal and entire purpose of posting our doc section assessments > Right on the front page of the wiki: > http://www.openplans.org/projects/plone-documentation/project-home > Each editor has given each doc a rating, posted comments, and some > have even gotten to the point where they are filling the gaps (see > Veda's recent email on docs published). > It's all there, out in the open, for the whole community to see. You > don't even need to be a member of the doc project on open plans to see > any of it. We can only show you where it is...we can't force you to > read it. > > > > 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. > > uh, why would we not have the doc team implement the documentation > team roadmap? We have a huge amount of members. It's just that only a > handful of people consistently step up and participate. > We're not some exclusive club here. If you're on the mailing list > you're considered part of the doc team. If everyone who subscribes to > this list chipped in just an hour or so of time, we could easily whip > this doc section into shape. Unfortunately, that's not the case. We're > doing the best with the volunteers and the time they have. ------------------------------------------------------------------------- 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 Dylan Jay-4
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... 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 |
||||||||||||||
|
|
JoAnna Springsteen
()
Re: If core code is undocumented it's broken (Was:where should developer documentation go?)
|
|
||||||||||||
|
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 |
||||||||||||||
|
Carsten Senger-3
()
Re: If core code is undocumented it's broken (Was: where should developer documentation go?)
|
|
||||||||||||
|
In reply to this post
by JoAnna Springsteen
Hi JoAnna,
hi docteam, I'm a single freelancer developer and am often stressed out to find a solution to a problem. Like many other developers I think. I took a look at the docteam-list after I stumbled across a new, changed development best practice on a plone-list where all docs I found tell something else. I read many postings and a bit of the wiki and I'm very impressed what's happening here. To be frankly I did not notice how much plone.org's documentations changed since the frontpage was redone long ago. Thank's to the docteam. JoAnna Springsteen schrieb: > On Tue, Nov 18, 2008 at 3:13 PM, Warner, Christopher > <[hidden email]> wrote: [...] > Actually, we do have a plan. > http://www.openplans.org/projects/plone-documentation/doc-team-roadmap > > We've figured out what our goals are...we're just in the process of > figuring out how we're going to accomplish/implement them. > > I highly suggest that anyone who wants to be involved read and know > this roadmap. This is what we are operating from. The reorganizing-documentation page helped me even more to see what's going on even if it isn't finished and more a collection of ideas. http://www.openplans.org/projects/plone-documentation/reorganizing-documentation >> Off the top of my head there are at least 4 different areas where >> documentation is severely lacking. [...] >> A framework section, explaining how to use the API. > > 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. [...] ..Carsten ------------------------------------------------------------------------- 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 |
