Oh Yeah - No worries mate :-)
--- Emmanuel Lecharny <[EMAIL PROTECTED]> wrote: > On 11/19/06, Ole Ersoy <[EMAIL PROTECTED]> wrote: > > > > Yeah - I think the point I was trying to make with > > respect to the parser is that our documentation > > process should follow some conventions that are as > > simple to use as possible. > > > The parser things was pretty much a joke, at this > point (pretty sure it was > a joke, wasn't it, ersin ? ;) > > I think the simple conventions we should follow up > to this point are the > confluence conventions. They have 3 advantages : > 1) they exist > 2) they are publicly available > 3) we already follow them. > > Converting documentation to another format is an > > important consideration. For instance suppose we > > wanted to convert it to a PDF, so that we could > easily > > produce a PDF book like the Maven Project / > Mergere > > did with their Maven 2.0 book. > > > Sure But I think that exporting the current cwiki > doco to pdf should not be > a real problem right now. (except that it will > produce a pile of paper I > would even be very reluctant to use in the smallest > room of my appartemnt, > regarding the content we currently have :) (hey, no > offense, guys ! just > wanted to say that we are far from having the right > content to produce a > book, not that the current content is bad :) > > So having documentation that is "Atomic" in the > sense > > that individual pieces can easily be moved between > > formats and templates is important. > > > confluence offers you that, I think. > > Sure we could just write some content really quick, > > but we could be setting ourself up for more work > later > > when we want to produce a MVN pdf book or > > something.... > > > Writing a book is quite a different process. I'm not > a specialist. Stefan > is. Let's hear about what he thinks first :) > > One really easy way to solve this is to make a > > template that incorporates the markup and Section > > headings for documentation with a specific > > communication goal. Like the Maven mini guides. > > > Never read them so far (may be this is the reason > why I'm so shittyy with > maven ...) But what I would say is that, for me, > maven is *by far* the last > example of good documentation i'm thinking of. The > mergere book is quite > good, but that's a different story. > > Then we can make an enumerated set of mini guides > > covering various ADS use cases. These can also be > > used to drive development and capture wish > > requirements. > > > Mini guides lead to maxi-confusion, I think. IMHO. > When you have something > like 50 min-guides, then it's soooo atomic that you > almost need a periodic > table to understand it. > > I.e. someone wishes we could do this. > > > > OK - Tell us how you would want that to look in a > mini > > guide.... > > > > That way the documentation for the functionality > is > > written before the functionality and the > functionality > > becomes use case driven. > > > > Personally I prefer to write the documentation > outside > > of confluence, because I think confluence has to > much > > "Noise" on the screen. > > > In fact, it doesn't matter a lot. The main advantage > of confluence, for > people like me, is that I can start some doco at > home, and continue at > office without having to save the text file on an > usb-key, or sending an > e-mail to myself. But that's just me. If you are > more confortable with any > other way to work, great. The main point, IMHO, is > to write doco, which is > the complicated part of the process ;) > > So if someone were to give me a simple template with > > cwiki markup in it > > > > Example: > > > > h1. Objective > > > > h1. Use Case Description > > > > h1. Activities Performed to Complete Task > > > > I'd be really happy and I could just cut and paste > > into confluence, while also storing the > documentation > > in the maven project. > > > Well, we don't have this right now. Look, as we are > pretty naked at this > time, what I would say is : go for whatever fits > your need and feeling about > doco. We will follow your proposal - being lazzy, if > someone propose > something, we are followers by essence :) - and if > something needs to be > discussed, then we will open a discussion about it > :) > > I just read on an infra thread that ASF policy for > doco is : "Commit first, > discuss later" :) > > Thoughts? > > > Well, this was some thoughts :) > > Emmanuel > ____________________________________________________________________________________ Sponsored Link $420k for $1,399/mo. Think You Pay Too Much For Your Mortgage? Find Out! www.LowerMyBills.com/lre
