Universal software documentation technique
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
assets
readme.md

readme.md

v1.2.0

Why?

Because plain text docs are boring, impossibly large and hard to maintain. And graphical diagrams are hardly compatible with version control systems like GIT. E.g. you can't use diff to see the difference.

What is it?

This documentation technique allows you to:

  • describe all possible scenarios that can happen in a given screen, component or script without language- or platform- specific syntax
  • describe them with whatever depth you want
  • express complex concepts using a compact, terse syntax
  • keep it under version control
  • create new features or changes descriptions as easily as changing few lines and pushing it to repo
  • describe the very top level of business logic as well as low level interactions within the code itself
  • accurately communicate with non-technically-educated people
  • interconnect multiple instances of Flowdocs

Usage example

Let's say we need to describe a mobile app, that is connected to api server. In the given case our goal is to describe authentication process.

1. Artboards

Use artboards to describe visual look of the given UI Artboards

Use intercatives to describe animations with Sketch Prototyping or Framer.

2. Client side docs

It's up to you whether to describe "invisible" part of logic of your app. We tend to abstract UX from internal code logic and therefore we describe only UX (what auser observes) in client-side Flowdocs.

Syntax for client side

|  - scene
>  - action
/  - initial state
=  - result
?  - if else statement

Scenes: Each scene described separetely from each other. Description assumes that reader is looking at the related artboard. If your page too complex then make it simpler describe components, not scenes. Seriously, make it simpler, if it's hard to describe it in docs, can you imagine frustration of a user who sees a scene for the first time.

Login

/ "Login" button is disabled until "email" and "password" inputs are filled
> Enter email and password; tap "LOG IN"
  ? email is malformed
    = snackbar message "Email is malformed"
  ? password is incorrect
    = snackbar message "Incorrect password"
  ? else
    = show loading indicator
    | Profile
> tap "Forgot Your Password?"
  | PasswordRecovery
...

PasswordRecovery

/ "RESET PASSWORD" button disabled until email input filled
> enter email, tap "RESET PASSWORD"
  ? email is invalid
    = snackbar "Email is invalid"
  ? email is not found
    = snackbar "Email not found"
  ? else
    = snackbar "Check your email"
    | SignIn
> tap "CANCEL"
  | SignIn

SignUp

/ "SIGN UP" button disabled until "email" and "password" inputs are filled
> Enter email and password; tap "SIGN UP"
  ? email malformed
    = snackbar message "Email is malformed"
  ? password incorrect
    = snackbar message "Incorrect password"
  ? else
    = show loading indicator
    | Profile
> tap "Forgot password"
  | PasswordRecovery

2. Server side docs

We recommend to use tools like Swagger for Api endpoint description and Flowdocs solely for logic, because quite often one doesn't want to bother about server-side logic and only wants to see input and output of a given method.

Server side syntax:

$  - function, that can be induced only by server
?  - if/else statement
{} - incoming data
=  - result
~  - response/call to client

Api methods:

In this example I'm using only Api methods descriptions for sake of simplisity, but feel free to adopt the same approach for different cases.

/signIn

{
  email,
  password,
}
? email invalid
  ~ snackbar message "Email is invalid"
? password invalid
  ~ snackbar message "Password is invalid"
? else
  = find user by email in database
    ? user not found
      ~ snackbar message "Email not found"
    ? password incorrect
      ~ snackbar message "Email not found"
    ? else
      $ openUserSession

/openUserSession

...

/signUp

{
  email,
  password,
}
? email invalid
  ~ snackbar message "Email is invalid"
? password invalid
  ~ snackbar message "Password is invalid"
? else
  = find user by email in database
    ? user found
      ~ snackbar message "User with this email already exists"
    ? else
      $ createNewUser

/createNewUser

...