Need Clarification about cukedoctor in agile project

[vikramvi]

Hi Rafael,

I've few queries wrt this tool please clarify

1. In my current company I've started following BDD. I maintain user stories in a github repo. Which itself is submodule of another github repo which runs UI tests to make sure user stories are "live" In this case why should I use the "cukedoctor" tool ?
2. I didn't clearly understand converting feature file into living documentation generator. Why is it needed ? Where do you maintain it ? How do you share with others ?
3. Once you convert to feature file to html format , how do you publish to everyone within company ? how internal website hosting is done ?

Thanks in advance.

Regards, Vikram

[rmpestano]

Hi @vikramvi,

short story is: Cukedoctor is used to convert Gherkin based stories into a readable living documentation, just that. By readable I mean with properly fonts, table of contents, which focus on the content and not on reports (as most of bdd tools). To reach this readability Cukedoctor uses Asciidoctor, a tool chain that is used to write documentation, books and so on. For example Hibernate documentation is using Asciidoctor.

Now to your concerns:

In this case why should I use the "cukedoctor" tool ?

If bdd documentation output is important for you then I'd recommend.

Where do you maintain it ?

Preferable within source code, documentation should "live" as close as possible to your source code. Should be versioned and delivered together.

How do you share with others?

Once generated it is a matter of copying it to a public site, for example each version of Database Rider project docs are published to gh pages (on each commit via CI server), see here.

Once you convert to feature file to html format , how do you publish to everyone within company ? how internal website hosting is done ?

I think its covered in 2 but I'll detail a bit. Technically speaking, a good place to publish it is where your software is built because docs are build alongside source code (usually as a step in your build pipeline. So for example it can be a Jenkins task which copies (for example using ssh or maven-scm-plugin) the generated docs to the public site/wiki.

Hope that clarifies your concerns and thanks for asking

[vikramvi]

Hi Rafael,

Thanks a ton for detailed answers. I will start using the tool and trying to understand each of the points you mentioned. In case of further queries , will ask you here.

Kind Regards, Vikram

[rmpestano]

:+1:

[rmpestano]

I've added some info on publishing docs here, maybe it helps.