Project analytics is a bit of a work in progress so it is constantly evolving to better suite the needs of our users and companies. At present we offer analytics for 3 different metrics, you will be able to select the comparison period in your project dashboard.

Total Viewers
Details the amount of users (Non unique) your documentation has received for the given comparison period, e.g this week vs last week.

Average Engagement
Details the average time that users spend viewing and navigating your documentation for the given comparison period, e.g this week vs last week.

New Viewers
Details the amount of new users (Unique) your documentation has received for the given comparison period, e.g this week vs last week.

If you have any ideas around analytics and reporting features that could be useful, please submit a feature request from the resources page of our website.

Documentation Analytics

The Docbloc platform can be navigated using a few main elements;

This will be shown when on the project select screen as well as all manage account and profile routes. When in the project view this menu will be available by clicking the project icon in the bottom left.

The project sidebar allows you to navigate the project details, more details on these in the project edit guides.

Navigating the platform

Within the Docbloc ecosystem there is a concept of teams, it allows companies to have multiple users within the account, and also allows users to belong to multiple accounts with the same login/personal details.


Creating a new team:
Creating a new team is simple, once logged in you can visit https://app.docbloc.co/create-team and follow the team creation process.

When logging in if you belong to multiple teams you will be asked to choose the team you want to login with, and from within the Docbloc dashboard you can click your user photo in the top right and a dropdown will appear with all the teams that you belong to.

The team details, users roles and permissions can all be managed from within the team settings section of the site, these will be covered in more detail in their own guides.

For help changing the team owner or to delete a team please, contact Docbloc support.

Working with teams

Introduction to Docbloc

Your dashboard consists of 3 main parts as follows

Navigation Bar:
On the left you have the Docbloc logo, you can use this to navigate back to this page from wherever you are in the app. On the right hand side you will have your company icon you can click on this to do various tasks such as switch team, edit profile, view team settings area, navigate back to the switch project screen.

Project List:
In the main area you will have a list of your active projects, the icon, title and url will be displayed for each.


Create Project Actions:
From this section you will have 3 options for creating a new project, you can either add one from scratch, import from postman or OpenApi or you can create a demo project with some demo content which can give you a starting point.


Dashboard

You can update your profile from either the topbar in non project screens or from the bottom right icon in your project editor window, once on the edit profile page you will be able to manage the following settings:

Personal details:
From this tab you will be able to update your name, avatar, password and timezone. Email address can only be updated by contacting a member of support to ensure account security.

Theme
Customize your app appearance by choosing either dark or light mode.

Notification Settings
We will always let you know about important changes, but you can choose what other marketing communications you would like to recieve here.

Edit Profile

The project editor is the main interface for your documentation management. It is split into 2 main parts, the sidebar/nav where you can navigate between project access settings etc. And the main editor window that will change depending on your selection in the sidebar. 
When you first open the project editor you will see a dashboard for your project that contains a few details about your project.

Project Information
This lists some useful info about your project including the project name, documentation url, availability and the active versions for the project.

Analytics
Project analytics is a bit of a work in progress so it is constantly evolving to better suite the needs of our users and companies. At present we offer analytics for 3 different metrics, you will be able to select the comparison period in your project dashboard.

Project Users
This is a list of all the users within your team that have access to the project along with their access level. For pro plans you are able to specify user access on a project by project basis.

Please see the Editing a project section of the user guides for full details on all project editing aspects.

Project Editor

The team settings area can be found by clicking the team settings button in the account popup either in the top left or in the bottom right depending on what screen you are on. 


From there you will be able to edit aspects of your team including the following:

Please see the team settings section for details on all areas of the team settings area.


Team Settings

Navigating the Platform

If you don't know where to start and you would like to create a project with dummy content you can do this from your dashboard; click the Demo Project option under the create project section a window will popup, when you click generate project it will create and navigate you to your new project.

Generating a sample project

Creating a new project is simple, from the main screen you see when you login to docbloc you can choose from one of the options to create a new project. Aside from the ability to create a project from scratch you can also import using either a postman json spec or an OpenApi json spec; you can also create a demo project if you would like to help you get started.

Once you have followed a step for one of the items, you will be redirected to your project launchpad which will provide you with some steps to get your docs live. This component will be replaced with your project dashboard once you have completed all the required steps.

How to add a new project

Docbloc supports creating a project from an imported postman collection. This can be done from your main dashboard / project select screen.

Navigate to the Postman import section and upload your Postman v2.1 collection. A detail screen will show with the general overview of the content that will be imported. Click the save and import button to continue to your project dashboard.

Please note our imports are still under development so if you spot any issues or improvements please visit our contact  or feature requests  system and send us the details :)

Importing from Postman

If you've created a new project and are having issues, or if you are having trouble creating a project please submit a support request  and and we will try our best to resolve any issues/queries that you might have.

New project troubleshooting

Docbloc supports creating a project from an imported open api json file. This can be done from your main dashboard / project select screen, choose the `Import Content` option.

Navigate to the Open API import section and upload your OpenApi/Swagger v3 json file. A detail screen will show with the general overview of the content that will be imported. Click the save and import button to continue to your project dashboard.

Open API / Swagger Import

Creating a new project

Advanced content pages allow pro project users to add additional content types to pages including tables, media, columns and rows.

Projects with this feature available will see the advanced content page editor instead of the default html editor that is available on non pro projects. When upgrading a project existing page content will automatically be converted to the new content page editor.

You can add items by clicking the + button and choosing an option from the menu.

Advanced Content Pages

The main content of your project is made up of what we call 'Items', each item has a different type and is for a specific purpose, as follows:

Groups
These are used to store other items, it's possible to nest groups as many levels deep as you need. They also have a title and description that will be used on the documentation to display your group intro

Endpoints
Endpoints are pretty self explanatory and are the main focus, see full user guides on editing endpoints for more details.

Content Pages
Content pages are simplified items that contain an html editor and you can add any content you need on here.

Models (Coming soon)
Shared models that can be used across endpoint requests and responses.

Errors (Coming soon)
Shared error messages that can be used as responses for endpoints.

Adding items to your project
You can add items to your project by clicking on the green add button, a window will show with the different types of items, select the one you want and it will be added to your items list in the sidebar. Click outside the window to cancel adding an item.

Content - Create Items

The content page editor can be found by clicking on a content page item in the content bar.

For content pages the title and the content can be edited. The content is an html editor that will display styling and elements in the same format on the page in your docs.

Content Pages

Pro projects have the ability to have versioned docs for cases when you need to provide support for older versions of your api.


How It Works:
When you create a new version all you need to do is give it a name, we will then copy the latest version of your documentation and all its items. You will be directed to your newly created version, this version will now become a pre-released version. More on how release statuses work bellow.

Release Statuses:
Your documentation versions will fit into the following statuses.

- CURRENT - This is the current version of the docs and the one that users will see when they view your docs.
- NEXT - This is the version above the current release, when users view this on the frontend they will be notified that it is a pre-release and is subject to change.
- PREVIOUS - This tag is given to all versions that are not the CURRENT, or PRE release versions. When viewed by users this will show a notification letting users know that they are using an old version of your documentation and that they should consider switching.


Once you have finished editing your documentation / released your api you can update the  NEXT release version to be CURRENT from your project settings under version settings 

Create & Switch Versions
You can create and switch versions by clicking on the version name under your project icon in the sidebar:

A window will popup with a list of versions as well as their status, and a button to create a new version.

Creating and Managing Versions

An endpoints details can be updated by clicking an endpoint item in the sidebar:

Method and route
You can specify the endpoint method from the dropdown and enter the route; on the element at the top of the page.

In the main editor window you will be able to update the endpoints title as well as the html content that appears in the same styling and formatting on your Docbloc.


Endpoints - Details

The parameter editor is the most complex part of the app, and has a bit of a learning curve. If you are having any trouble with it you can watch our video tutorial to help you get started.

Creating a new parameter
You can start by clicking the 'Create new' button to add a new parameter, you will be given a form that details the parameter as follows: 


Label
This is the label for your endpoint for example: user_name, email etc.

Type
You can choose the type from the dropdown menu; when choosing Object or object array you will be able to add child parameters to the item for example your api might take a user object with a few properties such as first_name, last_name, email etc.

Description
You can provide a paragraph or 2 of details for this parameter that users need to know.

Required
You can choose if a parameter is required or not and a flag will be shown accordingly.

Validation
A string value that details any validation on this parameter

Sorting & Editing
After creating the parameters you can drag and drop to reorder or place them under different parent parameters, you can also click the 3 dots on the side of an item to reveal its context menu; from the context menu you will be able to edit, duplicate, delete or expand.

Parent / Child Parameters
When creating a parameter with either a Object or Object array type you will be able to add children from the main editor view:

Clicking the create new link will then show you the create parameter form, parent/children can be nested as much as needed.

Endpoints - Parameters

Endpoint request and response examples are split into 2 different sections within the endpoint editor; Valid json needs to be entered for both, these can be either a json array or object, the field will indicate if the json is valid or not.

Endpoints - Requests & Responses

Groups are used as a hierarchy for other items and groups, they can be edited by clicking the 3 dots on the group item in the sidebar, and choosing edit group from the context menu that appears, you can also duplicate or expand a group from here.

The items sorting is done using drag and drop in the sidebar, you can drag into, out of and between groups.

For Groups the title and the content can be edited. The intro content is an html editor that will display styling and elements in the same format on the page in your docs.

Groups

The project editor is the main interface for your documentation management. It is split into 2 main parts, the sidebar/nav where you can navigate between project access settings etc. And the main editor window that will change depending on your selection in the sidebar. 


When you first open the project editor you will see a dashboard for your project that contains a few details about your project.

Project Editor Dashboard

For documentation that is set to private, you will need to create some access codes for the people that need access to the documentation. You can do this by visiting the Access tab in your project settings:

From here you can create new access codes, delete codes see details on usage and more.

Project Settings - Access Codes

Sooner or later you will need to remove older docs when they are no longer supported, you can do this in your settings panel under the delete version heading at the top of the sidebar. Please note project must have at least one version available at all times so this option is disabled when you only have one project version available, please use delete project instead.


When you delete a project version if its the CURRENT version sepecified for your project then the version before will become the CURRENT.

Project Settings - Delete Version

The project layout settings page will allow you to manage various layout and design elements of your documentation, please note that some features are only available for projects on the pro plan.

Project Settings - Layout

You are able to provide some custom urls that will show at the top of your documentation. 

Support URL - A link to your api support platform or a contact form.
API Key Details - A link to the page in your dashboard that allows users to manage api access tokens.

Or anything else you can think off that may be necessary.

When creating links other then your support link you provide a title and a url.

Project Settings - Links & Navigation

For best results your documentation needs 3 main images that are uploaded in the project settings -> logos and icons section these are as follows:

Icon:
This is used as the browser favicon, when sharing documentation urls with a preview, throughout the admin area and when users visit private documentation. We recomend that you use an icon that is 150px x 150px and is less than 20kb and has a transparent background.

Logo: 
This is the logo that gets shown in the main sidebar of your documentation when in light mode. Recomended image is 400px x 160px and less than 100kb in size, with transparency and looks good on a light background.

Logo (Dark Mode): 
This is similar to the regular logo except that it needs to be visible on a dark backgroun.



Note: All logos and icons are optional and if not provided the project name will be used instead. 

Project Settings - Logos & Icons

The Project Details tab includes settings that affect all of your project versions, details are as follows:

Project Name: 
The name of your documentation, this is used throughout the editor console and as the meta title in your project, if a logo is not provided this value will be shown instead in its place.

Page Title:
This is the title for your documentation that sits underneath the logo on the frontend documentation.

Visibility:
This controls the visibility of your entire application, you have 3 options:

Draft - Your documentation will not be available for anyone.
Public - Your documentation is publicaly available.
Private - Your documentation is available throuh passcode protected access (More details on private documentation can be found in the concept user guide).

Note: Previewing draft docs will soon be available for users, this will allow users to preview docs that have not been publised using their console login details

Active Version:
This controls the currently active version of your docs, this option is only available for projects on the pro plan with versioning enabled. More details can be found in the versioning user guides.

Project Settings - Project Details

Docbloc projects have the ability to have multiple editors/managers etc.

There are 3 main types of account roles in the system as follows:
Owner - This is the role given to the account creator, has the same permissions as admins but is also allowed to add admins
Admin - Has access to edit all projects and can create new projects as well as manage account and project users.
User - Has no access initially and needs to be added to each project individually.



When adding a user to the project under project settings you will only see users that role are set to user, and you will only see a list of users that have not been added to the account; you can follow the link to invite new users to your account if needed.

Custom Roles:
If your project is on the pro plan you will be able to give more granular control to peices of a project, you will need to create the roles in your account settings then select it from the roles dropdown in the add user window. See the account roles and permissions guides for more details.

Project Settings - Users & Roles

There are a few details that are specific to project versions rather then the entire project, this are as follows:

Version Name:
This is the human readable name for your project version, each version will also have a unique version code. a good example is V1,V2,V3 or master,beta,alpha

API Base Url:
This is the base url that is shown at the top of your documentation and will usually be different for each project version.

Introduction Text:
This is the text that is shown in the introduction part of your documentation, you might want to include details such as whats new in this release etc.

Project Settings - Version Details

Editing A Project

The billing history section of your account management area will allow you to view past and upcoming payments as well as download invoices:

Billing - History

From here you can manage your teams payment methods:

Billing - Payment Details

From here you can see an overview of all the subscriptions for your projects:

You will also be able to easily upgrade and cancel subscriptions

Billing - Subscriptions

Details

You can create and manage team roles & permissions here:


When creating a role you need to permissions from a predefined list. click the add role button, give it a name and choose the required permissions. Roles can either be project based or account based but not both.



Roles & Permissions

From your account management area -> users you are able to manage the users that exist on your team.


There are 3 main types of account roles in the system as follows:

Owner - This is the role given to the account creator, has the same permissions as admins but is also allowed to add admins
Admin - Has access to edit all projects and can create new projects as well as manage account and project users.
User - Has no access initially and needs to be added to each project individually.


You can manage user details by clicking the cog icon on the sidebar.


Docbloc

Welcome to the Docbloc User Guides