Complete Moron's Guide
|
|
| 1 2 |
|
Ricardo Newbery-2
()
Re: Fwd: Complete Moron's Guide
|
|
||||||||||||
|
On Apr 10, 2008, at 1:40 AM, Christian Schneider wrote: > Ricardo Newbery schrieb: >> No difference. The conclusion is the same. The "content" is what >> needed -- the "branding" isn't going to help. > > Again, how do you know that? I think it is going to help (note that I > have the decency to write "I think" and do not formulate an absolute > statement). *Any* statement you make is an expression of what you think. The qualifier "I think" doesn't add any more information or supply a real reason for your belief so it's usually superfluous. Most teachers of English composition and writing style guides will tell you that adding "I think" to your argument, or any personal reference such as "it seems to me" or "in my view", is usually unnecessary. But if it isn't clear... yes, this is "just" my opinion. Branding is a marketing tactic to get someone to choose your product by leveraging the reputation or familiarity of an already established brand. It is my "opinion" that the proposed title has neither an already established brand to leverage (the existing Dummies and Idiots books non-withstanding) nor any need to market itself at all, unless you intend to market this guide outside the context of the Plone documentation area and plan to leverage the "brand" into a series of Complete Moron guides. If neither of these two cases are true, then "it seems to me" that the burden is upon you to establish some foundation for your belief that this branding would help your audience better than just a simple descriptive and non-provocative title like "The Easy Guide". Not that you're required to convince me of anything... unless you really want to. :-) >> Now I'm confused. Good cop, bad cop? The original poster, John, >> clarifies that he believes that the community "endeavors to be >> helpful" and it "seems to favor an organic and somewhat cordial >> atmosphere". But you seem to be claiming otherwise. Again, I have >> to >> ask... what relevance does any of this have to the current >> discussion? > > Are you referring to what I wrote? I don't see the connection... and > even if I would see a connection I guess I would be entitled to my own > opinion. Of course you are entitled to your own opinion. I'm just trying to understand the point of this particular argument. Even if the Plone community was full of unhelpful jerks, what relevance would this have to the question of branding? Ric ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Balazs Ree
()
Re: Fwd: Complete Moron's Guide
|
|
||||||||||||
|
As a non-member of the documentation team let me also put in my own opinion. Having a documentation for absolute beginners, is great. But, please don't call it "Moron Guide". I would not feel good if I had to give an url to this document to some of my customers, or someone that I want to offer help to. About the success of the "XXX for Dummies" series: as a community we may or may not agree with the idea behind this naming, that should be our decision, independently of how succesful these series are or not. I am also sorry if the document is taken off from Plone domain but I also respect the rights of the authors to do so. Best wishes -- Balazs Ree ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Enovant JPR
()
Re: Fwd: Complete Moron's Guide
|
|
||||||||||||
|
In reply to this post
by Ricardo Newbery-2
On Apr 10, 2008, at 1:13 AM, Ricardo Newbery wrote: > > On Apr 9, 2008, at 9:54 PM, Enovant JPR wrote: > >> >> But now these guides are well branded and people know that when you >> get this dummies or idiots guide, you get something that actually >> works. The brand was Dummies Guide' and that allowed it to expand >> into >> a very successful franchise while in turn building the branding >> stronger. The fact that they chose a name that branded well via its >> clarity shows the intelligence of the intent. > > > We're still talking about a guide in the Plone.org documentation > area, right? What purpose does branding serve in this context? > Well, we were... that aside, branding works everywhere, even inside a community. For example, small and even large companies and organizations have branded internally to create projects and concepts to inspire or categorize groups and even attitudes. If the CMG project were accepted and worked well, then people would say oh, you want good docs, check out the CMG docs, they work! Branding is also helpful. Like the man and woman symbols on bathroom doors. It just helps for quick identification/communication. That way when someone visits your company and asks where the bathroom is, you don't have to go into a long explanation, instead you can just say down that hall and point. > > >>> What tendency is that? I'm not sure what you're trying to say here. >>> That the community is not helpful to newbies? You're basing this on >>> observations of one birds-of-feather meeting? >> >> I was only commenting about a single event, not the entire community. >> It is unfair to assume I am attacking an entire community. And >> regarding the event in question. I can understand the passion and >> excitement preventing people from noticing what is going on around >> them (Hey, there we all were in naples talking Plone, that's >> exciting) >> and merely disappointed that they were not doing what good >> instructors >> should do and read the room. Nobody is perfect all the time, I was >> just disappointed in watching it. Your extrapolation is incorrect. > > > Sorry, my mistake. Like I said, I wasn't sure what you were trying > to say. I'm still not sure what relevance it has to the current > discussion. > The current discussion has morphed as discussions do but the logic is interesting, your "not sure what relevance it has" but you are the one that began questioning my statements with a broad net extrapolated opinion? Questioning relevance after the fact seems out of context. > > >>>> There is nothing wrong with a morons guide and it should be >>>> introduced as an apex type of document not in any diminutive sense. >>>> As >>>> to Mr. Ricardo Newberys temptations to only send someone an idiots >>>> guide when he feels particularly snarky. I think he should >>>> seriously >>>> rethink his perspective. If that is his true feeling then he really >>>> does look down on some people rather than want to lift them up >>>> with a >>>> very informative idiots guide that probably knows how to explain >>>> things in simper terms than he does (otherwise he would not be >>>> considering sending them the guide in the first place). In >>>> complexity >>>> there is plenty of fault and richness, and we are all a part of the >>>> fault and the richness, if we participate earnestly. >>> >>> >>> Now, you're just being unfair and twisting my comments to mean >>> something totally opposite to my intent. My point, which should >>> have >>> been obvious, is precisely that I do not "look down" on people in >>> need >>> of help and wish not to insult them by pointing them to a document >>> who's first message is that they're morons. >>> >> >> I'm sorry. I did not realize that I was "twisting" your "comments to >> mean something totally opposite" to your "intent". I thought that >> when >> you said, "The only times I've ever felt tempted to give someone a >> "Dummies" guide is when I'm feeling particularly snarky." that you >> meant "The only times I've ever felt tempted to give someone a >> "Dummies" guide is when I'm feeling particularly snarky." >> >> Did I misread that? I could be wrong, but that line doesn't say to me >> "I do not look down on people in need of help". It says to me "The >> only times I've ever felt tempted to give someone a "Dummies" guide >> is >> when I'm feeling particularly snarky." >> >> Again, I could be wrong, but I don't read it the way you now say you >> intended it. I think your words are pretty direct and defined. > > > Please don't troll. You're quoting that sentence out of context. I'm not sure how you mean troll? My only ref. is fish and web trolling. If you mean trolling because I repeatedly quoted your statement in order to avoid misquoting you by placing it in perspective of itself in relation to your later explanation, then i guess it is trolling from your perspective. It is certainly possible that there is a sub cultural connotation relevance to the sentence, but from my perspective, what you stated was quite clear and it seemed that i was taking in it context from what I could tell. I apologize if i misunderstood your dialectic and/ or indigenous connotations within the sentence wording and structure. > >> Personally, I'm -1 on "moron". Makes it hard to point people to it >> without inadvertently insulting them. The only times I've ever felt >> tempted to give someone a "Dummies" guide is when I'm feeling >> particularly snarky. > > In context, I hope it's clear that my desire is to be able to point > people to good documentation without insulting them. That's not to > say I've *never* been tempted to insult someone -- I doubt anyone > can make that claim -- but I think I can safely say that I've rarely > succumbed to such temptations. I would say that this communication is clear on that point, but not the original communication. Best, John > > > Ric > ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Enovant JPR
()
Re: Fwd: Complete Moron's Guide
|
|
||||||||||||
|
In reply to this post
by Ricardo Newbery-2
On Apr 10, 2008, at 3:55 AM, Ricardo Newbery wrote: > > On Apr 10, 2008, at 1:40 AM, Christian Schneider wrote: > >> Ricardo Newbery schrieb: >>> No difference. The conclusion is the same. The "content" is what >>> needed -- the "branding" isn't going to help. >> >> Again, how do you know that? I think it is going to help (note that I >> have the decency to write "I think" and do not formulate an absolute >> statement). > > > *Any* statement you make is an expression of what you think. The > qualifier "I think" doesn't add any more information or supply a real > reason for your belief so it's usually superfluous. Most teachers of > English composition and writing style guides will tell you that adding > "I think" to your argument, or any personal reference such as "it > seems to me" or "in my view", is usually unnecessary. > > But if it isn't clear... yes, this is "just" my opinion. Branding is > a marketing tactic to get someone to choose your product by leveraging > the reputation or familiarity of an already established brand. It is > my "opinion" that the proposed title has neither an already > established brand to leverage (the existing Dummies and Idiots books > non-withstanding) nor any need to market itself at all, unless you > intend to market this guide outside the context of the Plone > documentation area and plan to leverage the "brand" into a series of > Complete Moron guides. You are stating that the proposed title is not an established brand? The idiots and dummies guides have so solidly branded the concept that a morons guide, in a marketing sense, would be said to be pre branded by association conceptually. > > If neither of these two cases are true, then "it seems to me" that the > burden is upon you to establish some foundation for your belief that > this branding would help your audience better than just a simple > descriptive and non-provocative title like "The Easy Guide". Not that > you're required to convince me of anything... unless you really want > to. :-) The Easy Guide is pretty boring from a marketing/branding perspective. But who knows, names can change? > >>> Now I'm confused. Good cop, bad cop? The original poster, John, >>> clarifies that he believes that the community "endeavors to be >>> helpful" and it "seems to favor an organic and somewhat cordial >>> atmosphere". But you seem to be claiming otherwise. Again, I have >>> to >>> ask... what relevance does any of this have to the current >>> discussion? >> >> Are you referring to what I wrote? I don't see the connection... and >> even if I would see a connection I guess I would be entitled to my >> own >> opinion. > > > Of course you are entitled to your own opinion. I'm just trying to > understand the point of this particular argument. Even if the Plone > community was full of unhelpful jerks, what relevance would this have > to the question of branding? > > > Ric > > > > > ------------------------------------------------------------------------- > This SF.net email is sponsored by the 2008 JavaOne(SM) Conference > Don't miss this year's exciting event. There's still time to save > $100. > Use priority code J8TL2D2. > http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone > _______________________________________________ > Plone-docs mailing list > [hidden email] > https://lists.sourceforge.net/lists/listinfo/plone-docs ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
JoAnna Springsteen
()
Re: Complete Moron's Guide
|
|
||||||||||||
|
In reply to this post
by Balazs Ree
The Plone Docs team tries very hard to maintain the documentation we
have and deliver new documentation in a timely manner. We've had a lot of successes in the past year. For the first time, we delivered an up to date end user manual with the newest release of Plone. We are actively holding more frequent sprints just for docs. We've even convinced some devs. to deliver documentation with their add on products (see CSSManager). We have strategic goals that we are actively working on. But we are all volunteers. It's hard to coordinate and find the time to actually do the work. However, we do have goals ahead of us that we are actively working towards. These goals will allow us to function more efficiently as a team, maintain the doc set in a more effective manner, and improve on what we already have. It's too big of a task for one or a few people to do alone. It's also fairly hard to reach consensus when dealing with a large group of people. But we move ahead, doing the best we can. We all know our documentation isn't perfect and needs improvements. No one is saying otherwise. I firmly believe that the only way we are going to improve things is if we work together towards a common goal in well thought out manner. My point being...Christian, et. al. I admire what I think you're trying to do, all disagreements aside. But I do think it's probably the best decision to work on it outside of plone.org. Now I'm hoping that we can be done with this discussion. The attitudes and the negativity need to stop in order for all of us to be productive, no matter what path we chose. The taunting, insulting, and pointing of fingers stops now as well. I operate on the basis of "if you don't like something, change it". You have options on how you participate in change....you can change from the inside or chose to operate outside of things. I'm choosing to change things from the inside of plone docs. Your feelings may lead you to a different choice. Either way I wish all parties the best of luck. We all have the goal of a usable doc set in mind and in that sense we all benefit. JoAnna ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
mikeBOS
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Christian Schneider-10
Christian Schneider wrote:
> Ok, the big amount of negative feedback (from a small amount of people) > led us to the decision that we will host the CMG somewhere else. > I always thought the www.learnplone.org site was a brilliant idea: A place for Plone editors and authors to find help without wandering through a forest of developer docs. The reason guys can't find a can of beans in the pantry isn't because the beans aren't clearly labeled, it's because there are so many other cans. I've never liked the Idiot/Dummy titles, but it hasn't put me off of reading them. If letting the authors name it helps motivate them to keep writing it, then I think that's a pretty small price to pay. (My pick would have been "Layman", "Automath", or even something random like "Mongoose Guide to Plone". Do Mongooses eat pythons?) It's *hard* to get Plone help. Though there are a lot of friendly Plone people willing to help, it's hard to ask the right question, and it's often harder to understand the answers you get. I really appreciate the effort this team makes. -- Mike Combs irc: mikec-boston ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Steve McMahon
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Christian Schneider-10
On Thu, Apr 10, 2008 at 12:39 AM, Christian Schneider
<[hidden email]> wrote: > - the fact that one keeps running into "internal server errors" and "bad > gateways" when editing stuff on plone.org certainly doesn't help either The need to improve this situation is something I think we're all agreed on. The demands on Plone.Org have risen very rapidly. The sysadmins and board are actively working on this. We're dedicated to making sure Plone.Org gets the resources it needs. -- ______________________________________________________ Steve McMahon Reid-McMahon, LLC [hidden email] [hidden email] ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
vedaw
()
Re: Never mind
|
|
|
In reply to this post
by Christian Schneider-10
Hi Christian,
Just a couple of quick comments... I am one of the people responsible for the frustration everyone is feeling right now. Not all of the doc center changes we put into place were successful, and unfortunately, a lot of intended improvements did not happen due to my own unavailability. That said, I finally have some availability and hope to get the project moving again with the help of others. I come armed with survey results from the entire Plone community, and whether or not I agree with some of the items on the list, I will listen and try to incorporate the requests however I can. And, there is some consensus toward the trailhead approach, we just need to flesh it out more and identify where it falls short or will require extra effort. Maybe the project hasn't been moving forward lately, but that's about to change. In the interest of having a fuller understanding of the various propositions, can you explain one thing for me? You say, "The 'trails' idea was proposed by me more than a year ago, combined with a concept for single-sourcing docs by having a drop-box for people to leave (somewhat formalized) docs in and using the doc team to split the information up and incorporating it into the existing docs." What do you mean by single-sourcing? One author? Thanks, and and one other favor: I'd like to look closer at the docs you've been working on, if that's ok. I do think there's value in them, semantics aside, and it's a lot easier to read a single tutorial than follow a patchwork of tutorials written by a variety of authors. If you'd grant me access to them, I'd appreciate that. - Veda
|
||
|
Martin Aspeli-2
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Christian Schneider-10
Christian Schneider wrote:
> All in all we feel that there's a severe structural problem in the doc > team, as well as in many other teams in the community. We still love > Plone and the community in general and that's why we will keep acting as > shit-stirrers in the hope of helping build awareness which might then > lead to changes. That sounds grand, but I think you'll find that if you keep stirring the shit, all you'll achieve is to mix the shit better. It's not a way to facilitate change, however well-intentioned the stirring of the shit may be. > The CMG has been deleted from the doc section, you can stop feeling > offended on behalf of others now. Case in point. Martin -- Author of `Professional Plone Development`, a book for developers who want to work with Plone. See http://martinaspeli.net/plone-book ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Martin Aspeli-2
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by vedaw
Hi Veda,
> Just a couple of quick comments... I am one of the people responsible for > the frustration everyone is feeling right now. Not all of the doc center > changes we put into place were successful, and unfortunately, a lot of > intended improvements did not happen due to my own unavailability. That > said, I finally have some availability and hope to get the project moving > again with the help of others. Great! I'm glad you're taking this on. > I come armed with survey results from the entire Plone community, and > whether or not I agree with some of the items on the list, I will listen and > try to incorporate the requests however I can. And, there is some consensus > toward the trailhead approach, we just need to flesh it out more and > identify where it falls short or will require extra effort. Maybe the > project hasn't been moving forward lately, but that's about to change. I wonder if it makes sense for you and Laura Trippi to join forces and share the burden a bit. Perhaps your combined availability would be sufficient? > In the interest of having a fuller understanding of the various > propositions, can you explain one thing for me? You say, "The 'trails' idea > was proposed by me more than a year ago, combined with a concept for > single-sourcing docs by having a drop-box for people to leave (somewhat > formalized) docs in and using the doc team to split the information up and > incorporating it into the existing docs." What do you mean by > single-sourcing? One author? The trails idea has floated around this team for a long long time. There was a discussion before about turning the documentation into something where you could mark up different parts and then re-compose them into single documents. A kind of "slice and dice" approach, if you like. I don't personally believe in this, because it would be hard to build a coherent story from anything more granular than a full document as it was written by its author. I also don't think we should be looking for technology solutions to what is primarily an information architecture problem. Martin -- Author of `Professional Plone Development`, a book for developers who want to work with Plone. See http://martinaspeli.net/plone-book ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Christian Schneider-10
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Martin Aspeli-2
Martin Aspeli schrieb:
> That sounds grand, but I think you'll find that if you keep stirring the > shit, all you'll achieve is to mix the shit better. It's not a way to > facilitate change, however well-intentioned the stirring of the shit may be. Yeah true, but look what this little commotion has created already... a bit of a discussion about the structure of the docs, some discussion on audience vs topic based (primary) sorting and a proposal to embrace buildout as integrator technology and realisation that there need to be better docs on that subject to be able to do so. So stirring seems not to be too bad a thing really... ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
JoAnna Springsteen
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Martin Aspeli-2
> I wonder if it makes sense for you and Laura Trippi to join forces and
> share the burden a bit. Perhaps your combined availability would be > sufficient? In the works doll. ;) look for a meeting scheduled sometime next week, open to all interested parties. (there is another IA thread with the link to the agenda items if anyone wants to add some) > The trails idea has floated around this team for a long long time. Yes it has. Actually, I think martin proposed it almost 2 years ago. > There was a discussion before about turning the documentation into > something where you could mark up different parts and then re-compose > them into single documents. A kind of "slice and dice" approach, if you > like. It's called single sourcing. Reusing paragraphs in different documents. It makes sense for some document sets. But in those cases, you use a single sourcing tool like AuthorIt. Moving to a single sourcing style of documentation is an involved process and takes several years for businesses with dedicated staff to do it. It's a nice solution when it works but it's usually more for print documents, not online doc sets. I also don't think we should be looking > for technology solutions to what is primarily an information > architecture problem. + 1. this is content issue, not so much a technology issue. I have my frustrations with PHC but changing that doesn't change what's written inside of it. ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Christian Schneider-10
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by vedaw
Hey Veda,
vedaw schrieb: > Hi Christian, > > Just a couple of quick comments... I am one of the people responsible for > the frustration everyone is feeling right now. Not all of the doc center > changes we put into place were successful, and unfortunately, a lot of > intended improvements did not happen due to my own unavailability. That > said, I finally have some availability and hope to get the project moving > again with the help of others. > > I come armed with survey results from the entire Plone community, and > whether or not I agree with some of the items on the list, I will listen and > try to incorporate the requests however I can. And, there is some consensus > toward the trailhead approach, we just need to flesh it out more and > identify where it falls short or will require extra effort. Maybe the > project hasn't been moving forward lately, but that's about to change. I don't think it is your fault really, from what I remember the changes you did were very welcome and we're moaning on a much higher level nowadays (anyone remember the doc sections startup page before it was re-designed by Veda et al... ARGH). I do think that the amount of changes was limited because of the imminent Plone 3 release and the target to get the doc section vamped up for that, so you did the best that was possible in the given time. > In the interest of having a fuller understanding of the various > propositions, can you explain one thing for me? You say, "The 'trails' idea > was proposed by me more than a year ago, combined with a concept for > single-sourcing docs by having a drop-box for people to leave (somewhat > formalized) docs in and using the doc team to split the information up and > incorporating it into the existing docs." What do you mean by > single-sourcing? One author? Single-sourcing is actually a word I learnt from JoAnna last year. I proposed the trails approach and envisioned docs that were basically very short (although not too short) segments of documentation that just focus on one step that is very self-contained. A "document" would then just be a trail (e.g. of references) that link the different segments together. This would make it possible to re-use documentation-segments (we gave them a neat name that I can't recall anymore) in other docs, which would make updating hell of a lot easier. The fact that information does not get repeated (much) is called single-sourcing (I hope I remember that correctly, JoAnna?). The solution I had envisioned included version-information for each document-segment, so a trail could be copied and given a new version number to take into account and, voila, the new doc is finished just by updating the segments that need updating and saving those changes with a new version number... the unchanged stuff can be fallen back to. Apparently this would require a big new tool, PHC was and is nowhere near that, but one could have created a slightly slimmed down version (i.e. no real single-sourcing, but at least a decent amount of segmentation) of that just with tutorial pages and tutorials. This would require that the policy towards new submissions would have to change though, so the idea was to have a drop-box where new document-segments could be posted. This information would have to be edited and incorporated into the existing docs by a doc-team member (turning them into real editors). This is some work and it was said back then that it was not practicable. I disgreed because the rate at which new docs are coming in is not that staggering, and the recyclability would take away a lot of the maintenance hell that comes with the way the docs are organized right now (there will be more and more docs to manage over time, at some point this will have to fail unless the docteam grows proportionately). I know that it was ambitious, but I also believe that it would have been possible to implement in a timeframe that would have produced results much sooner, even if not the whole doc section could have been moved to the new format. An idea of mine was to have 2 doc sections temporarily, the old one for reference, and the new type for new stuff and to gradually move the old stuff into. By "moving old stuff" I mean that the information of the old docs is extracted and put into the new format (possibly involving a lot of copy&paste), NOT that the objects are moved themselves. This effort seemed only a little bigger than the effort that is needed to find and mark or updated outdated docs. > Thanks, and and one other favor: I'd like to look closer at the docs you've > been working on, if that's ok. I do think there's value in them, semantics > aside, and it's a lot easier to read a single tutorial than follow a > patchwork of tutorials written by a variety of authors. If you'd grant me > access to them, I'd appreciate that. Well sorry to say that but I deleted them from plone.org earlier today. It will be a while before they get published online again, I need to develop a new kind of PHC-like tool and set up a website with it. I don't have too much spare time but I will try to keep it going and will post again once I have something to show (probably with only very basic tutorials on setting up python/buildout and some skinning). Cheers, Christian ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
Laura Trippi-2
()
Re: Never mind: Before you go...
|
|
||||||||||||
|
In reply to this post
by Christian Schneider-10
Hi, Christian, and all,
Thanks for a spirited discussion of the state of Plone docs. I've created a page for it in the Docs IA project wiki and linked to the discussion threads in Nabble: http://www.openplans.org/projects/plone-documentation/morons-guide-discussion Is anyone willing to cull from this discussion those ideas that could feed into the redesign of the docs area -- and put them into bullet points so it's easily scannable? That would be very helpful. You could do just points from your own posting(s), and sign them, or do the entire thread. It would also be great if someone would be willing to summarize suggestions from this discussion at the upcoming IRC meeting on docs IA. Anyone? And, if you care about the design of the Plone docs area, please participate in that meeting. Vote for your preferred day/time here: http://www.openplans.org/projects/plone-documentation/irc-meeting-on-docs-ia And on a process note: Although I'm championing the current IA redesign effort, because I volunteered at the Planning Summit, I'm doing it at several removes because of other obligations and unexpected redirections in my work. I'm really sorry about that. It's doubtless holding the project back. But I've been inching it forward as best I can. From a broader perspective, though, time, other obligations (like, earning a living), and the enormity of the task at hand seem to be The Key "structural problems" with the Plone docs team, to me. Working with and through the dynamics of distributed, decentralized teams is a big challenge, too. So, if you can, thanks for taking a few minutes to reflect and feed suggestions forward to the larger documentation project before this discussion ends. ::Laura Christian Schneider wrote: > - we don't see the restructuring of the doc section on plone.org to be > moving anywhere. The "trails" idea was proposed by me more than a year > ago, combined with a concept for single-sourcing docs by having a > drop-box for people to leave (somewhat formalized) docs in and using the > doc team to split the information up and incorporating it into the > existing docs. This found some support in the doc team at first but was > then brutally shattered by a trio of rockstars, saying that "it would > never get anywhere". Seems like the current approach doesn't either, eh? > > - we really don't feel like wasting our time with battles of the sort "i > don't like the word morons, change it" and "you should really not do > what you're doing but do what I tell you instead". Not because we don't > like to hear what others have to say but because of the fact that the > arguments are ill-founded and based on assumptions and taste rather than > facts. The discussion about the name and on if we should really do what > we're doing cost us about 8 hours (the team all together, not each 10 > hours). Had we invested those into the guide itself we would now be able > to release the first CMG on settiing up Python 2.4 in a reproducible > way... go figure. > > All in all we feel that there's a severe structural problem in the doc > team, as well as in many other teams in the community. We still love > Plone and the community in general and that's why we will keep acting as > shit-stirrers in the hope of helping build awareness which might then > lead to changes. > The CMG has been deleted from the doc section, you can stop feeling > offended on behalf of others now. > > Cheers, > Christian > > > ------------------------------------------------------------------------- > This SF.net email is sponsored by the 2008 JavaOne(SM) Conference > Don't miss this year's exciting event. There's still time to save $100. > Use priority code J8TL2D2. > http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone -- Laura Trippi :: latrippi.com :: 707.322.0692 ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
Christian Schneider-10
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by mikeBOS
Hey Mike,
Mike Combs schrieb: > I always thought the www.learnplone.org site was a brilliant idea: A > place for Plone editors and authors to find help without wandering > through a forest of developer docs. The reason guys can't find a can of > beans in the pantry isn't because the beans aren't clearly labeled, it's > because there are so many other cans. I agree, the amount of docs and the lack of structure are problematic. The idea we had with CMG was to simmer down the information contained in other docs and put them into small, recyclable chunks. Thereby we'd reduce the amount of documentation and also make it possible to offer more "trails" focusing on different questions asked. Because of the recyclability the amount of information would not grow, but different audiences would be able to follow different trails that lead through the same amount of document-segments, just on different paths, maybe includign some more/less explanations here and there. > I've never liked the Idiot/Dummy titles, but it hasn't put me off of > reading them. If letting the authors name it helps motivate them to keep > writing it, then I think that's a pretty small price to pay. (My pick > would have been "Layman", "Automath", or even something random like > "Mongoose Guide to Plone". Do Mongooses eat pythons?) That sounds like a good idea too, John what do you think? Are you emotionally attached to the morons or are we open for discussion on this still? ;o) > It's *hard* to get Plone help. Though there are a lot of friendly Plone > people willing to help, it's hard to ask the right question, and it's > often harder to understand the answers you get. I really appreciate the > effort this team makes. Thanks, it's good to have some encouragement. I will need to write a new product/package to put that concept into practice and that will take quite a while as it is very complex (at least for my tiny brain). I would have gone for a more primitive approach just to see if it gets accepted on plone.org/documentation, but since we can't seem to be able to get a separate subsection in which we can order things appropriately we might as well go for the real thing right away, even if it means an awful lot of work. I'll try to be quick, maybe we'll set up stuff in a very primitive manner first (folders with docs in them) just to have the information up (because i can see the development of that package to take quite a few months)... we'll see. Greetings from Switzerland, Christian ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
|
|
vedaw
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Christian Schneider-10
Hey there Christian,
Thanks for clarifying all of that, that does indeed help. I've pulled the relevant pieces out and incorporated into the new openplans wiki for this project. http://www.openplans.org/projects/plone-documentation/morons-guide-discussion Ultimately, I think for now it comes down to creating a "what good looks like" for trailhead documents -- and your docs and Martin's tend to follow the granular approach that makes this work. It's only necessary in some situations, so it won't mean a whole rethinking of how we do all of our documentation. The additional functions you mention, such as flagging with version, etc. are probably more than we can do right now, but that's not to say it isn't a good idea. I think we should look at a model whereby this works -- perhaps the tool that Joanna mentioned and see if we could repurpose something like that for Plone in the future. And, the idea of editors and the dropbox has been well-received, and I'm fully in favor of it. We just need to make it happen. It's partially on my back burner, but not forgotten. Lastly, your idea of a "development" documentation area... that can probably be accomplished with staging. When we were making the modifications to the new PHC area last year, we had a staging area to work with so that the changes could be rolled in seamlessly. I assume this is what you meant? Do let me know when you have the docs available again. Thanks, - Veda
|
||||||||||||||
|
|
Enovant JPR
()
Re: Never mind
|
|
||||||||||||
|
In reply to this post
by Christian Schneider-10
Christian Schneider wrote:
> Hey Mike, > > Mike Combs schrieb: >> I've never liked the Idiot/Dummy titles, but it hasn't put me off of >> reading them. If letting the authors name it helps motivate them to keep >> writing it, then I think that's a pretty small price to pay. (My pick >> would have been "Layman", "Automath", or even something random like >> "Mongoose Guide to Plone". Do Mongooses eat pythons?) > > That sounds like a good idea too, John what do you think? Are you > emotionally attached to the morons or are we open for discussion on this > still? ;o) I'm always open to new ideas Christian. I just had not put any further thought into it as yet. > I'll try to be quick, maybe we'll set up stuff in a very primitive > manner first (folders with docs in them) just to have the information up > (because i can see the development of that package to take quite a few > months)... we'll see. > > Greetings from Switzerland, > Christian > > > ------------------------------------------------------------------------- > This SF.net email is sponsored by the 2008 JavaOne(SM) Conference > Don't miss this year's exciting event. There's still time to save $100. > Use priority code J8TL2D2. > http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone ------------------------------------------------------------------------- This SF.net email is sponsored by the 2008 JavaOne(SM) Conference Don't miss this year's exciting event. There's still time to save $100. Use priority code J8TL2D2. http://ad.doubleclick.net/clk;198757673;13503038;p?http://java.sun.com/javaone _______________________________________________ Plone-docs mailing list [hidden email] https://lists.sourceforge.net/lists/listinfo/plone-docs |
||||||||||||||
| Free Embeddable Forum Powered by Nabble | Help |
