DemoTime Documentation

Welcome to the DemoTime documenation! If you don't find the help you need here please feel free to reach out to us via GitHub!

Table of Contents

How it Works

Here at DemoTime we set out to emulate the demo process that we experienced on a routine basis as part of an Agile software development workflow. What we found is the demo process for software development is pretty similar to showing off any piece of work you have to share with others. Perhaps it's a new logo, a short marketing blurb, a new screen cast to share with your customers, or heck, maybe it is code after all!

As a result, we tried to keep the process as simple as we can, while still ensuring an experience that meets the needs of both the stakeholders that are reviewing a piece of content, and the needs of the content creator. The general process works like so:

  • Content creator creates content
  • Content creator creates a demo and assigns Reviewers to the Demo
    • A content creator can also add an optional co-owner to the demo (someone who can create and edit the contents of a demo)
  • Reviewers leave feedback via comments
    • If necessary the Content Creator(s) upload new revisions after receiving feedback
  • Reviewers approve Demo
  • Content creator(s) close Demo
  • Celebrations!

Creating A Demo

Creating a demo is a fairly straightforward process (we hope!). As a Demo owner all you need to do is create some static files that you can upload that shows off your work. We support video, audio, images, documents and whatever else you may wish to upload to share with others (though video, audio and images are the nicest).

Once you're ready create a demo, just follow these easy steps:

  1. You create a piece of content, let's call it a new logo.
  2. Go into a Project
  3. Click New Demo
  4. Insert a meaningful title
  5. Link back to your ticketing system where the work was requested
  6. Provide a brief description of the work performed
  7. Attach your new logo, or as many files as you need!
  8. Pick the people that need to see and approve your new work
  9. Create the demo!

Now you should be looking at a scene similar to this:

Let's start off by explaining what a few of the things on this screen mean:

  • Owner: This is the person who has created and thus owns the demo
  • Reviewer State: This represents the overall state of the people assigned to review this Demo. If all of them have approved the Demo, then it will state 'Approved'. If there's a mix, 'Reviewing', and if everyone's rejected it, the state will be 'Rejected'.
  • Demo State: This reflects if the Demo is 'Open', 'Closed', or 'Aborted'. Aborted occurs when a Demo Owner closes a Demo before it has reach a full approval status.
  • Case Link: The link to request for work, likely in your company's issue track
  • Reviewers: This section lists the people assigned to review your Demo, and their state. Also if you or others need to add more reviewers, there's a handy box there for that as well! We allow non-owners to add Reviewers to a Demo, because it's a common use case. Maybe Samantha in QA realizes that Jennifer in Product needs to see the Demo as well! We're an inclusive bunch.
  • Demo Revisions: We'll come back to this one shortly, it deserves more words than a bullet can hold

The Demo Flow

Alright, now we have demo out there for people to view, and we've received a bit of feedback from our users via the comments system. It turns out they didn't like the color blue that you chose. First, know that you have our sympathy because that color blue was actually fantastic as far we're concerned. Second though, you'll probably want to listen to your employer and pick the correct blue.

Now you've updated your work, and you've captured a new screen shot of your logo with the proper color of blue. Simply go to your Demo and click "Update Demo" at the top. You'll notice this form looks a lot like the form you filled out earlier, and we assure you it's for good reason!

What you're doing now is creating a new Revision of your Demo. We consider each Revision as a conversation about a particular piece of work. What happened with the wrong color blue is now in the past. Now we want to talk about your new asset that has incorporated the feedback of others. You can enter something to that effect in the "Revision Description" field if you wish, or you can leave it blank. Most important on this screen is to upload your new logo for the Reviewers to look at.

Afterwards you'll be on a screen similar to what you saw earlier except you'll now notice that there are 2 Revisions in the "Demo Revisions" section. You can still go back and discuss the last Revision if necessary, but more than likely you'll mostly be talking about the new and updated revision. We like history though, and that's why we've opted to preserve it, while focusing everyone on a new conversation about a new asset.

Finally, all reviewers are reset to 'Reviewing' after a new Revision has been added. This ensures that everyone gets a chance to view the new item that is being Demoed. Otherwise, this flow is the same as your standard Demo flow.

Completing a Demo

We consider a Demo to be complete once all Reviewers assigned to it have reached a consensus. Once everyone has moved to "Accepted" or "Rejected" a Demo is "complete". It is however still Open until the Demo Owner clicks the "Close Demo" button located at the top of the demo.

We leave this power in the Demo Owner's hands because ultimately, we don't think that anything should ever end in a state of rejection. Remember, a Demo is a conversation, and in general it's good practice to not leave a conversation unresolved or angry! A state of Rejection to us implies that more Revisions are needed to complete the work that was agreed upon from the outset.

Once a demo is closed, it can be reopened, but more often than not we feel you'll likely prefer to simply create a new Demo after it's been reworked a bit. We're still learning from our users though, so perhaps you can inform of us of stronger user cases. We do love feedback!

Reviewing a Demo

We've strived to make life as easy as possible on Reviewers, and as such, we hope that Reviewers will find their job to be fairly simple. Here's how the flow looks to a typical reviewer:

  • Receive an email that you've been added to a demo
  • Go and view the Demo
  • Review the assets, description, reviewers and other comments
  • Feel free to add more Reviewers if you find people are missing
  • If you're not satisified with what is being presented, comment and let the owner know
  • When you're satisfied, click the "Approve" button.
  • Celebrate!

Web Hooks

Web Hooks exist to allow you to tightly integrate DemoTime into you or your company's workflow. We can fire web hooks on the following events:

  • Demo Created
  • Demo Closed
  • Demo Aborted
  • Demo Updated
  • Demo Reopened
  • Demo Approved
  • Demo Rejected
  • Comment Created

A Project Admin can define these on a per-project basis. Simply choose an event you wish a hook to fire on, and give it a URL you wish for us to post to, and then we'll start POSTing to the defined URL when those events occur.

For example, say you wanted to put a link to each Demo created in your company's issue tracker. You would define a Web Hook for "Demo Created" and point it at a service in your infrastructure. You could then capture the data we POST to you, and then use that data to create a comment in your system's issue tracker via their API.

The payload that we send look like the following:

{
    "webhook": {
        "pk": 1, "project_pk": 1, "trigger_event": "comment", "target": "http://requestb.in/ouy32rou"
    },
    "review": {
        "description": "description",
        "url": "/reviews/default-project/review/212/rev/1/",
        "project": {
            "groups": [{
                "project_pk": 1,
                "group": {
                    "description": "Default DemoTime Group",
                    "name": "Default Group",
                    "slug": "default-group",
                    "members": [{"username": "user", "is_admin": true, "pk": 23}],
                    "pk": 1,
                    "group_type": {"pk": 1, "name": "Default Group Type", "slug": "default-group-type"}
                },
                "is_admin": true
            }],
            "description": "Default DemoTime Project",
            "url": "/projects/default-project/admin/",
            "name": "Default Project",
            "slug": "default-project",
            "members": [{"project_pk": 1, "username": "user", "user_pk": 16, "is_admin": false, "display_name": "User"}],
            "pk": 1, "is_public": false
        },
        "approved_count": 2,
        "pk": 212,
        "reviewing_count": 2,
        "is_public": false,
        "reviewers": [{"review_pk": 212, "reviewer_status": "reviewing", "reviewer_pk": 742, "name": "User", "user_pk": 7}],
        "case_link": "https://example-issue-tracker.tld/issue-123",
        "title": "Issue Title",
        "followers": [{"review_pk": 212, "name": "Follower", "follower_pk": 184, "user_pk": 6}],
        "rejected_count": 0,
        "reviewer_state": "reviewing",
        "creator": "Creator", "state": "open"
    },
    "comment": {"comment": "Comment Text", "attachment_count": 0, "thread": 239, "name": "Commenter"},
    "token": "88587e9966234dd08faffd6f5cf5c10b"
}

Special note: The "Comment" section only appears during a "Comment Added" triggered event