qi4j documentation

[chris snow]

Qi4j seems like an interesting project, but I'm put off by the lack of documentation.

The existence of a link for a 2 hour tutorial suggests to me that there is a reasonable quantity of information one needs to learn about Qi4j.  However, without the tutorial, I can only guess that it will take me a substantial amount longer to get the equivalent knowledge through trial and error.  

Also, to use an opensource library at my place of employment, one of the acceptance criteria is availability of documentation.  Qi4j would not meet the acceptance criteria.

I hope this feedback is taken positively.

[Jiri Jetmar]

Hi Chris, 

welcome here & thank you for the feedback. 

Indeed, availability of documentation is a very essential aspect - especially what you are thinking 

to use such product in a enterprise/business environment. 

So at least from my perspective Qi4j is here not in a good light. It has to be improved. I;m working 

now more then a year nearly daily with and on Qi4j and most of the questions and issues that are popping

up I;m able to answer myself. But it took us a lot of time & effort to get the required experience. 

Looking now back, I can say that not really the Qi4j Code needs to be described in details but the concepts 

as they are in many aspects a bit different from the "mainstream". All of this cool COP feature and the way

how the Domain Model is structured and created. That's pretty cool. 

I was already thinking about to start something like "Qi4j in Action" but this is a full time job and for 

now I do not have the capacity. Also it will be required that Niclas & Paul (the two real Hackers behind this Project)

are helping with this undertaking.

This are just my 5cents on this.. 

Cheers, 

Jiri 

--
You received this message because you are subscribed to the Google Groups "qi4j-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to qi4j-dev+u...@googlegroups.com.
To post to this group, send email to qi4j...@googlegroups.com.
Visit this group at http://groups.google.com/group/qi4j-dev.
For more options, visit https://groups.google.com/d/optout.

[chris snow]

Hi Jiri,

Thanks for the feedback.  It is really useful to hear your actual experience getting up-to-speed with Qi4J.

If you do decide to write a book, I would buy a copy for sure!

Many thanks,

Chris

[Jiri Jetmar]

Hi Niclas, 

"sure it will take a long time, but what the hell. It takes the world some time to catch up as well."..

Indeed, thats the case. What I realized during onboarding some guys for the project I started is that not 

only the pure code is a real challenge, but mostly the COP style that is e.g. used for the domain modeling. 

Means from my point of view the "Book" should be a kind of hands-on on the code but also a description 

about the architectural patterns. 

Ok, I will make a proposal for the Table of Contents. 

Cheers, 

Jiri

 

2014-05-21 9:30 GMT+02:00 Niclas Hedhman <nic...@hedhman.org>:

On Tue, May 20, 2014 at 4:55 PM, Jiri Jetmar <juergen...@gmail.com> wrote:

> I was already thinking about to start something like "Qi4j in Action" but this is a full time job and for
> now I do not have the capacity. Also it will be required that Niclas & Paul (the two real Hackers behind this Project)
> are helping with this undertaking.

Could you produce a Table Of Contents, i.e. listing Chapters and Sections? I think a big bulk of what is needed already exist, and if we knew better what is missing for a book, then I and perhaps Paul could help out filling in the meat... sure it will take a long time, but what the hell. It takes the world some time to catch up as well.


Cheers
--
Niclas Hedhman, Software Developer
河南南路555弄15号1901室。
http://www.qi4j.org - New Energy for Java

I live here; http://tinyurl.com/3xugrbk
I work here; http://tinyurl.com/6a2pl4j
I relax here; http://tinyurl.com/2cgsug

[Paul Merlin]

Hi guys,

Sounds like a good idea!

Cheers

/Paul


Jiri Jetmar a écrit :

[Dominic Jones]

With regards to documentation in general... I still refer quite heavily to the website docs while trying to learn and conceptualize Qi4j's concepts. I feel I understand a lot, but there are still holes in the documentation where I have built my learning from actually tinkering with the framework. There are also some inconsistencies... (e.g. some of the Concerns/SideEffect stuff is copy pasted with a few errors remaining..)

I would like to contribute to cleaning up some of those docs. How can I submit pull requests to update those documentation files, or get permissions to do that? (Any reviewers would be appreciated of course..)

[Niclas Hedhman]

So, documentation sits "side-by-side" in the qi4j-sdk repository on GitHub. We are using Asciidoc, and it requires a bit of installs on your local system to generate the static files locally. Please refer to AsciiDoc documentation, and if any question ask me.

To make it easier, just give us your GitHub ID, and I will add permissions for you.

And if anything is unclear, just ask and I will try must best to answer it as detailed as I can.

Cheers

--

You received this message because you are subscribed to the Google Groups "qi4j-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to qi4j-dev+u...@googlegroups.com.
To post to this group, send email to qi4j...@googlegroups.com.
Visit this group at http://groups.google.com/group/qi4j-dev.
For more options, visit https://groups.google.com/d/optout.