Building Documents in Azure DevOps
Common Questions and Tutorials
Intro to Smart Docs
Why are we focusing on documents?
Almost every team we encounter is using some document authoring system to house and/or report their requirements.
By offering both unrestricted style to present requirements, and templates that create structure, Smart Docs makes building documentation an easy to implement staple for all teams.
Step 1) Build a Meta Template
When creating any Smart Doc, you create it on top of a Meta Template.
This means your Meta Template defines exactly which work items are allowed in your Document and where.
This is why we start our tutorials by teaching how to build a basic Meta Template first.
Step 2) Create and Edit Your Smart Doc
Creating a Smart Doc allows your team to implement a document-driven workflow, where you are adding in existing project requirements into documentation or building new requirements from the document interface.
Whichever you are choosing to do, you need to be able to create and edit a Smart Doc using the Meta Template you created in Step 1.
Step 3) Versioning and Create Reusable Doc Templates
Smart Docs includes all of the necessary versioning capabilities.
You can get a red-line view of changes that are made between document versions, and easily save new versions of documents at any time. You can output older versions of documents and more.
We cover versioning and building reusable document templates in this video.
Complete Training Module
Inserting Full Work Item
Hierarchies into a Smart Doc
Do you already have a Work Item hierarchy in your backlog that you would like to add to your Smart Doc quickly? Watch this video to see how you can drag a full Work Item hierarchy into a Smart Doc at once.
Automatic Risk Scoring
Learn how to use automatic risk scoring – a process of attaining a calculated score indicates how severe a risk is, based on several factors.
Importing Microsoft Word Documents to Smart Docs
Learn how to import Word documents directly into Smart Docs.
Go to previous module
Go to next module
Smart Docs is a tool that allows you to create, and distribute documents from your Azure DevOps project.
You are able to turn your existing requirements into a document that can be distributed as Word, PDF, or HTML directly from your project. You can also author new requirements simply by adding to your document.
These documents you create have full version control, bi-directional behavior between your project work items and those that exist in the document, and can be sent for online reviews with e-signatures.
Smart Docs can include any work item type.
You even can setup your Smart Docs in such a way that restricts where certain work items can be placed in a document – this feature is called a Smart Docs Meta Template (see Step 1 video above).
Meta Templates provide:
- Increased consistency across team members who create documents
- Easy to follow structure for new team members who are less familiar with a specific document type
- The ability to make reusable document templates that have both content (like intro, goals, scope) already laid out with their own structure.
Smart Docs has a “Save as template” feature that can be used in any Smart Doc at any time.
This means you can create a “BRD template” or an “SRS template”, or any template you want, that includes pre-built content with a defined structure.
Interested in creating a reusable document template?
Check out Step 3 video above.
There are two ways to “insert” work items into a Smart Doc.
You can author a brand new requirement into your project through the Smart Docs interface. The requirement / work item you create here will be accessible everywhere in your project.
You can also insert a work item using our “Insert” tab found in the toolbar of any Smart Doc. This “Insert” tab will allow you to pull in work items that already exist within your Azure DevOps project.
Both of these methods are covered in the Create and Edit Your Smart Doc video above.
Smart Docs allows you to easily add in new work items to your project.
You can create a meta template for each Smart Doc which will help you restrict which work items can be added to each level of a Smart Doc.
For a quick introduction to Smart Docs you can check out the above videos, or check out Week One of our Modern Requirements Bootcamp.
We know how tedious document approval processes can be.
That’s why we create a Review process that can be invoked from the “Review” tab in the Smart Docs toolbar.
The “Review” tab will open a popup window that allows you to quickly and easily set who should be a part of the Review, provide a description and due date, and send the review request to all Review members selected via email.
When members invited to Review click “Start Review Session” in an email, they will be brought to our Review module where they can easily use comments, approvals, and rejections to facilitate change.
You can see your Smart Doc in the Review module, from the Smart Docs view in the Review module.
This question requires a three-piece answer.
1) The work items that are created in a Smart Doc are created within your Azure DevOps project.
2) The Document work item which holds the relationships that make up your Smart Doc is stored within your Azure DevOps project.
3) The file that is used by Modern Requirements4DevOps to construct your Smart Doc is stored in your TFVC/GIT source control.
This means that the Document and the work items from your Smart Doc are easily query-able, and can be found within your project. As per the file stored in your source control, you will never need to interact with this file.
Smart Docs are not locked during editing.
This is because a Smart Doc consists completely of requirements from your project. We do not lock requirements that are currently in documents as the purpose of a Smart Doc is to flex and change with the changes that are made to your requirements.
We handle authoring conflict by saving the latest revision of a “Save” action.
Smart Docs was built to give you a clean, easy to use document interface which allows you to easily interact with requirements. You can open a requirement using the “Open in Standard Editor” button on the Smart Docs toolbar to open the Standard Editor.
But, if you want to add rich-text to your requirement you can double-click any work item in your document. This will open the Modern Requirements4DevOps Smart Editor, which will allow you to adjust any rich-text fields your requirements might already have.
The Smart Editor interface affords your teams the ability to change the text properties, add tables, control and resize images, and all of the features you would typically expect from Microsoft Word.
Open any Smart Doc you currently have and double-click an item inside.
Once you have made changes to a rich-text field, open the requirement anywhere else in your project and you will see your changes reflected in the work item there too!
Modern requirements is bi-directional!