packages/featurebook/README.md
FeatureBook
===========
[](https://github.com/jkroepke/featurebook-js)
[](https://www.npmjs.com/package/@jkroepke/featurebook)
[](https://www.npmjs.com/package/@jkroepke/featurebook)
[](https://david-dm.org/jkroepke/featurebook-js?path=packages/featurebook)
[](https://codeclimate.com/github/jkroepke/featurebook-js)
[](https://codeclimate.com/github/jkroepke/featurebook-js/coverage)
[](https://lerna.js.org/)
* [Introduction](#introduction)
* [Rationale](#rationale)
* [Usage](#usage)
* [Specification format](#specification-format)
* [Gherkin source files](#gherkin-source-files)
* [featurebook.json](#featurebookjson)
* [.featurebookignore](#featurebookignore)
* [SUMMARY.md](#summarymd)
* [Public API](#public-api)
* [Development environment](#development-environment)
* [Contributing](#contributing)
* [Project roadmap](#project-roadmap)
* [License](#license)
## Introduction
FeatureBook is a command line tool (and [Node.js](https://nodejs.org) library) for generating beautiful system
specifications from [Gherkin](https://github.com/cucumber/cucumber/wiki/Gherkin) source files.
[Here](https://github.com/SOFTWARE-CLINIC/featurebook-examples) are the example specifications you can play with.
## Rationale
Even in 2017, there are development teams that don't know how to apply
[Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) or some other
[Agile methodology](https://en.wikipedia.org/wiki/Agile_software_development) in day-to-day business. Believe it or not
but that's the matter of fact. Doing just daily meetings at 9 or 10 a.m. doesn't really mean that you're in the Agile
mode. With business analysts or other business folks it's even worse. Most of them haven't heard the buzzwords Scrum or
Agile. Therefore, it's not surprising that so many people undervalue specifying unambiguously what the system is
supposed to do. Instead, we are given 200 pages Microsoft Word documents that, after a short while, become a maintenance
nightmare and complete mess to read and understand.
FeatureBook is here to help you creating living documentation from Gherkin source files (suitable for DEV or QA guys)
and publish it in a format accessible for people who may not know how to work with source control systems or who are not
interested in seeing all of the source code. We bring the fun back into writing documentation!
What's more, the authors of FeatureBook are ready to help you writing system specification for real-life complex systems
and applications. If it's not a top secret mission critical beast, feel free to submit an issue where we can discuss
the details publicly. Otherwise let's meet in person in Warsaw, Poland.
If you buy the tickets and we like the destination, we'll fly over and do the training for you and your team!
(Especially we're looking forward to seeing Albania one day.) The outcome would be a FeatureBook tailored for your
system.
## Usage
Before installing FeatureBook, you will need the following:
* Node.js v4.x+
* [npm](https://www.npmjs.com) (which comes bundled with Node) v2.1.0+
FeatureBook can be installed (or updated if it's already installed) from npm:
```shell
$ npm install -g @jkroepke/featurebook
```
You can serve the current directory as a system specification:
```shell
$ featurebook serve --port 3000
```
Or simply build a PDF document:
```shell
$ featurebook pdf
```
To list all available commands and options:
```
$ featurebook --help
Usage: featurebook [options] [command]
Commands:
serve [options] [spec-dir] serve <spec-dir> as a system specification
pdf [options] [spec-dir] build the specification PDF document
html [options] [spec-dir] build the specification HTML document
Options:
-h, --help output usage information
-V, --version output the version number
```
To display help for a given command:
```shell
$ featurebook serve --help
Usage: serve [options] [spec-dir]
serve <spec-dir> as a system specification
Options:
-h, --help output usage information
-p, --port <port> port on which to listen to (defaults to 3000)
```
FeatureBook can be used with [Gulp](https://github.com/SOFTWARE-CLINIC/featurebook-gulp-example) to generate
a system specification as part of your continuous integration process.
## Specification format
A system specification is a directory containing:
* Gherkin source files organized into subdirectories
* The `assets` directory for images and videos that you can refer to from within the Gherkin source files
as well as summary descriptors
* Optional directory descriptors (`SUMMARY.md`)
* An optional specification descriptor (`featurebook.json`)
```
|-- assets
| `-- images
| |-- analytics.png
| |-- lock_box.jpg
| `-- time_tracking.png
|-- administrating
| |-- employee_management.feature
| |-- project_management.feature
| `-- reporting.feature
|-- authenticating
| |-- admin_authentication.feature
| |-- employee_authentication.feature
| `-- SUMMARY.md
|-- non_functional
| `-- service_level_agreement.feature
|-- time_tracking.feature
|-- unparsable.feature
|-- SUMMARY.md
|-- featurebook.json
`-- .featurebookignore
```
There are a few conventions:
* A single Gherkin source file contains a description of a single feature.
* Source files have the `.feature` extension.
* A feature name displayed in the navigation tree is inferred from the corresponding Gherkin file name, i.e. it's
a titleized base file name. For example, `service_level_agreement.feature` becomes **Service level agreement**.
* You can use [Markdown](http://en.wikipedia.org/wiki/Markdown) in Gherkin source files and directory descriptors (`SUMMARY.md`).
The FeatureBook's Markdown parser recognizes the `feature://` and `asset://` URL schemas so you can cross reference features
and images contained in the `assets` directory.
### Gherkin source files
A Gherkin source file usually looks like this:
```gherkin
# language: en
# featurebookDisplayName: Service Level Agreement Overwrite
Feature: Service level agreement
Keeping our customers happy is really important. This is why we cater for
the highest availabilty.
Scenario: New account creation
Given there are "100000" users registered on the system
When I create a new account
Then I should be taken to my dashboard within "5" ms
Scenario: Homepage page access
Given "1000" users are hitting the homepage simultaneously
Then each user should get a response within "2" ms
```
> NB Featurebook recognizes the `featurebookDisplayName` comment to overwrite the name of a given
> feature which is displayed in the navigation tree.
### featurebook.json
The `featurebook.json` contains specification's metadata, i.e. title, version, authors, and contributors.
```js
{
"title": "Time Tracking",
"version": "1.0.0",
"authors": [
{
"firstName": "Richard",
"lastName": "Feynman",
"email": "rfeynman@gmail.com"
}
],
"contributors": [
{
"firstName": "Isaac",
"lastName": "Newton",
"email": "inewton@gmail.com"
}
]
}
```
### .featurebookignore
A `.featurebookignore` file specifies files that featurebook should ignore when traversing the specification directory.
For example, a typical [SpecFlow](http://www.specflow.org) project contains `.feature` and auto-generated `.feature.cs`
files. To ignore the auto-generated files you can create `.featurebookignore` with the following content:
```
# Ignore auto-generated C# code
*.cs
```
> Note that featurebook implicitly adds the following patterns to the ignore list: `featurebook.json`, `SUMMARY.md`,
> `.featurebookignore`, `assets`, `dist`, `.git`.
### SUMMARY.md
Typically, this is a textual description of features and scenarios contained in a given directory.
The summary of the root specification directory should give a general ovierview and reading guidelines.
```
# Time Tracking
Best time tracking system for a small business. A simple online timer with a powerful timesheet calculator.
It is recommended to start reading the [admin authentication](feature://authenticating/admin_authentication.feature) feature.
```
## Public API
Most of the time, you will be using FeatureBook directly from command line. You can, however, call FeatureBook
programmatically from your Node.js module. [Here](https://github.com/SOFTWARE-CLINIC/featurebook/wiki/Public-API) is the
public API.
## Development environment
> To try out the latest development version clone this repository and [link](https://docs.npmjs.com/cli/link) the featurebook package:
> ```
> $ git clone https://github.com/jkroepke/featurebook-js.git && cd featurebook && npm link
> ```
### npm packages
## Contributing
You wanna contribute to FeatureBook? That is truly great!
[Here](https://github.com/SOFTWARE-CLINIC/featurebook/wiki/Contributing) are some tips to get you started.
## License
Code is under the [MIT](https://opensource.org/licenses/MIT).
Fork of https://github.com/SOFTWARE-CLINIC/featurebook