Documentation Flavoured Development

README.md

In Documentation Flavoured Development a change in the documentation can indicate a code change.

It builds on top of markdown by adding an extra rule. The syntax is two forward slash (//) at the beginning of a line. The first line contains a chekbox which indicates if the feature is ready or not. [ ] indicates an unchecked checkbox and [x] indicates a checked checkbox. The following lines prefixed with slashes may contain references for developers to find a file, class, method or variable. At least one reference should be added when the feature is "done" and no more than three is recommended.

Two type of static documentation can be generated from this. The first is without technical information containing only the lines not prefixed by //. The second is with technical information where the status of the section of the documentation indicated with color and the references are shown.

Markdown can be version controlled with this diff can show changes in the documentation. While references can help developers find the necessary bits of code. With tests one can be sure that a change does not break other parts of an application.

example.md

Step 1 - New section

Documentation:

// [ ]

The following theme colors are defined:

"primary", "secondary", "success", "info", "warning", "danger"

Implementation:

None

Step 2 - Implement

Documentation:

// [x]
// resources/assets/sass/_variables.scss:$theme-colors

The following theme colors are defined:

"primary", "secondary", "success", "info", "warning", "danger"

Implementation:

resources/assets/sass/_variables.scss

$theme-colors: (
        "primary": $primary,
        "secondary": $secondary,
        "success": $success,
        "info": $info,
        "warning": $warning,
        "danger": $danger,
);

Step 3 - Updated section

Documentation:

// [ ]
// resources/assets/sass/_variables.scss:$theme-colors

The following theme colors are defined:

"primary", "success", "info", "warning", "danger"

Implementation:

resources/assets/sass/_variables.scss

$theme-colors: (
        "primary": $primary,
        "secondary": $secondary,
        "success": $success,
        "info": $info,
        "warning": $warning,
        "danger": $danger,
);

Step 4 - Updated code

Documentation:

// [x]
// resources/assets/sass/_variables.scss:$theme-colors

The following theme colors are defined:

"primary", "success", "info", "warning", "danger"

Implementation:

resources/assets/sass/_variables.scss

$theme-colors: (
        "primary": $primary,
        "success": $success,
        "info": $info,
        "warning": $warning,
        "danger": $danger,
);