Scott,
I don't know if you meant those 5 steps as a confession of sorts. If so, I'll add that I am
personally guilty of those.
No time, no impetus.
As I told Chris Snow before, I read the codes easily enough. Eg. if I had a question about
JobManager, it just takes me 5 minutes read the answer from the source codes. Horrible folks like
me don't bother much with documenting OFBiz.
By the way, I also find it difficult to merge in my enhancements into OFBiz. No time. So how many
committers are there now? Actually, the better question is, how many contribution reviewers do we
have?
Jonathon
Scott Gray wrote:
Hi All,
Whenever I come across something new while looking at the code or reading
the mailing lists, my thoughts usually run along these lines:
1. I think I'll add that to the docs
2. Where shall I put it?
3. I/We need to create a better structure
4. I don't think I have the time or "big picture knowledge" to do this
5. I need to get back to what I was doing
And then I leave it at that
I think if we had a relatively full table of contents as a starting
point it
would be much easier to add snippets here and there with out them being
disorganized and hard to find. Then the hard work would be in cleaning the
pages up every now and again rather than deciding where to put things.
Regards
Scott
On 11/04/07, David E. Jones <[EMAIL PROTECTED]> wrote:
Christopher,
It's really great to see people interested in working on
documentation, especially interested enough to actually put something
together like this.
I'd like to make a small suggestion, for you and for anyone else
interested in a documentation effort: just as with source code, the
most effective way to work on documentation is to start with what
exists and work on improving it incrementally. There is a lot of
documentation on the docs.ofbiz.org site, and room for many thousands
of hours of work to improve and flesh out that documentation.
The great thing about helping with incremental improvements on
existing documents (even if the incremental improvement means a
reorganization or refacturing or the like; though that is obviously
dangerous when just starting out) is that your efforts become part of
something bigger, and with enough people doing this eventually the
combined effort will result in something great.
-David
On Apr 10, 2007, at 11:42 PM, Christopher Snow wrote:
> For the past few months, I have been trying to put together some
> technical documentation on ofbiz. I wanted the book to be detailed
> and accurate, but I have found it difficult to get answers to a lot
> of my questions on the mailing lists. I have found the whole
> process very tiring, and wasteful of time as I am having to spend a
> lot of effort working things out by looking through code. Maybe
> my emails are too rude? Maybe the mailing lists aren't working
> (what about lists for tech-user, functional-user, dev, docs)?
>
> Eclipse BIRT have got it right. They have provided an excellent
> users manual (field guide) and an excellent developers guide
> (integrating and extending BIRT). That really ramps up your
> knowledge of BIRT before looking at the code. With ofbiz, I've had
> to pretty much dive straight into the code (and spend time weaving
> my way through classpath loaders, container loaders, etc, before
> getting to find what I needed).
>
> Anyway, I've uploaded my scribbles if anyone finds it useful but an
> awful lot of work is needed to finish it off.
>
> > http://docs.ofbiz.org/download/attachments/1218/ofbiz_tech.pdf
>
> See you in a few months ...
>
> --
> This message has been scanned for viruses and
> dangerous content by MailScanner, and is
> believed to be clean.
>
------------------------------------------------------------------------
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.5.446 / Virus Database: 269.2.0/756 - Release Date: 4/10/2007 10:44
PM
