There is already a separate project for this:
https://github.com/jbehave/jbehave-site/tree/master/site-frontend/src/site/content
It is the overall doc front-end published to jbehave.org. There we can
develop a less-technical and more user-oriented (cross module,
core/web/etc ...) documentation.
As for the wiki, I'm grown a bit sceptical of its usefulness. No doubt
it's immediate and easy to add things, but much less easy to maintain
when the bulk of the docs grows. I much prefer file-based and
processed docs that can be published online, but also packaged and
downloaded as offline static docs.
With the advent of git (and github) the collaboration become just as
easy, with all the advantages of centralised source control.
So, feel free to provide pull requests to the above project.
On 14/03/2014 16:54, Hans Schwäbli wrote:
Hello Josef,
I think the technical part of JBehave is really intended for software
developers, so it requires that knowledge.
JBehave is a tool with a lot of features and has its complexity. It is
well designed, of good quality and free. So there are of course some
drawbacks like little documentation.
Anyone can participate in creating such documentation, and some people do.
I personally would hope, that an official Wiki is established for
JBehave. That could help to solve that. It cold be helpful if the
documentation is clearly separated into a part for story writers with
no programming skills and for step implementers (developers).
I could establish that official Wiki if the JBehave owners agree, so
that people can easily participate in creating missing documentation
and updating it in a central place of knowledge.
2014-03-06 14:36 GMT+01:00 Josef Dietl <jo...@dietl.org
<mailto:jo...@dietl.org>>:
Hi Janusz,
Thanks for taking up this topic. I was having similar problems to
get started, and for organizational reasons, I couldn't approach
the group.
I don't mean to offend anybody. Everybody here is incredibly
helpful, and the software is really great. But the learning curve
is wild. Given the deep questions I saw here while lurking, I
wasn't exactly inspired to step up, despite all the helpful
attitude of Mauro and everybody.
A bit about myself: I'm not a full-time developer, I'm a project
manager with a passion for continuous improvement of our
development practices. I'm good enough to occasionally find
something in a code review, to make a prototype or an automated
test, but my focus is on providing the optimal environment for the
development team so that /they/ can maximize their productivity.
So in order to get them to look at JBehave and [T|AT|B]DD, I had
to learn Maven and set up JBehave on my own in a branch of the
project to demonstrate the value-add.
To cut a long story short, once I was through, adding stories and
tests on top of the existing set-up was cool and convincing, but
the path there could have been smoother.
When I was working for the W3C, we had a saying: make the simple
things simple and the hard things possible. JBehave doesn't
exactly work like that, but once I had reached the "hard" things,
I also found traction in the documentation and the sample projects.
I don't have the role to suggest anything here, but I did ask
myself repeatedly whether it wouldn't be possible to be more
explicit about the first steps. Back then, I've tried my best here
->
http://digitaler-heimwerker.de/2012/10/26/howto-maven-spring-und-jbehave/
(unfortunately German). If a check with Google Translate suggests
that this is basically useful, I'd translate and tweak this and
its sibling post (below) as needed and contribute it.
Re-reading the post, I find that I struggled most on these topics:
1.What is the /simplest/ possible working configuration of
JBehave? (there's a description on the site, but no full
example... what are the main classes, what is their relationship
to each other? What do I need to import from where?
Reverse-engineering the thinking steps from the example projects
just didn't work for me.)
2.Depending on JBehave configuration and Maven configuration:
Where do I have to put this file, the stories and the step
implementations?
3.And then, specifically for my almost-simplest-possible set-up:
how does all this relate with Spring.
In hindsight, the biggest problem was #2: Which file goes where...
(or, more precisely, as everything is configurable: which
configuration determines what goes where, and what are the defaults?)
For a slightly more advanced topic, there's even a post in
English:
http://digitaler-heimwerker.de/2013/03/04/mocking-file-access-for-testing-with-jbehave-and-easymock/
I hope this helps. JBehave is really great, and I hope this
message is advancing its progress.
Thank you all for your great work!
Best wishes,
Josef
*From:*Janusz Kowalczyk [mailto:kowalczykjan...@gmail.com
<mailto:kowalczykjan...@gmail.com>]
*Sent:* Donnerstag, 6. März 2014 12:58
*To:* user@jbehave.codehaus.org <mailto:user@jbehave.codehaus.org>
*Subject:* [jbehave-user] Why JBehave repo examples and website
are the worst example of work ever created by the any of the open
source communitties?
It's truly remarkable that I haven't gave up yet in my attempts to
use JBehave many after days wasted on trying to figure out how to
run examples give on the jbehave.org <http://jbehave.org> or the
ones available in the project's repo.
Does any of the project members heard of Developer Experience?
Are there any chances that this will change in near future or this
project will keep to scare off more people?
Cheers
J
