- Specification format
- Gherkin source files
- Public API
- Development environment
- Project roadmap
Even in 2017, there are development teams that don't know how to apply Scrum or some other Agile methodology 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.
Before installing FeatureBook, you will need the following:
- Node.js v4.x+
- npm (which comes bundled with Node) v2.1.0+
FeatureBook can be installed (or updated if it's already installed) from npm:
$ npm install -g @jkroepke/featurebook
You can serve the current directory as a system specification:
$ featurebook serve --port 3000
Or simply build a PDF document:
$ 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:
$ featurebook serve --helpUsage: serve [options] [spec-dir]serve <spec-dir> as a system specificationOptions:-h, --help output usage information-p, --port <port> port on which to listen to
FeatureBook can be used with Gulp to generate a system specification as part of your continuous integration process.
A system specification is a directory containing:
- Gherkin source files organized into subdirectories
assetsdirectory for images and videos that you can refer to from within the Gherkin source files as well as summary descriptors
- Optional directory descriptors (
- An optional specification descriptor (
|-- 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
- 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.featurebecomes Service level agreement.
- You can use Markdown in Gherkin source files and directory descriptors (
SUMMARY.md). The FeatureBook's Markdown parser recognizes the
asset://URL schemas so you can cross reference features and images contained in the
Gherkin source files
A Gherkin source file usually looks like this:
# language: en# featurebookDisplayName: Service Level Agreement OverwriteFeature: Service level agreementKeeping our customers happy is really important. This is why we cater forthe highest availabilty.![Analytics](asset://assets/images/analytics.png)Scenario: New account creationGiven there are "100000" users registered on the systemWhen I create a new accountThen I should be taken to my dashboard within "5" msScenario: Homepage page accessGiven "1000" users are hitting the homepage simultaneouslyThen each user should get a response within "2" ms
NB Featurebook recognizes the
featurebookDisplayNamecomment to overwrite the name of a given feature which is displayed in the navigation tree.
featurebook.json contains specification's metadata, i.e. title, version, authors, and contributors.
"title": "Time Tracking""version": "1.0.0""authors":"firstName": "Richard""lastName": "Feynman""email": "email@example.com""contributors":"firstName": "Isaac""lastName": "Newton""email": "firstname.lastname@example.org"
.featurebookignore file specifies files that featurebook should ignore when traversing the specification directory.
For example, a typical SpecFlow project contains
.feature and auto-generated
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:
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. ![Time tracking](asset://assets/images/time_tracking.png) It is recommended to start reading the [admin authentication](feature://authenticating/admin_authentication.feature) feature.
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 is the public API.
To try out the latest development version clone this repository and link the featurebook package:
$ git clone https://github.com/jkroepke/featurebook-js.git && cd featurebook && npm link
You wanna contribute to FeatureBook? That is truly great! Here are some tips to get you started.
Code is under the MIT.