Documentation with Azure Wikis

Azure Wikis offer an effective way to create and manage your project documentation within Azure DevOps. In this guide, we will walk you through creating and using wikis, along with highlighting best practices for organizing your technical documentation.

Creating a New Wiki

To set up a new wiki in Azure DevOps, navigate to your project and select the Wiki option located under the Overview section in the left sidebar.

Click the option to begin setting up your wiki. Once selected, you will be presented with two choices:

• Create a project wiki (Provisioned Wiki): A standalone wiki hosted directly on Azure DevOps. This option provides a blank canvas where you can begin by adding a title and initial content to your main page.
• Publish code as a wiki (Published Code Wiki): Transforms existing Markdown files in your repository into an organized wiki view. This option integrates your documentation directly with your codebase.

Working with a Provisioned Wiki

Once you create your provisioned wiki, think of the main page as the headquarters for your documentation. Several management options become available, such as adding sub-pages, editing existing pages, or even deleting pages as your project evolves.

Building a hierarchical structure is straightforward. You can easily add sub-pages under the main page, ensuring that your documentation remains organized and easily navigable.

The built-in editor supports Markdown and HTML, making it simple to format your content. Features such as image insertion and resizing enhance your documentation, enabling you to create rich, detailed pages.

Additional helpful features include:

• Print functionality: Create hard copies of your documentation.
• Work item linking: Directly connect documentation to project tasks.
• Revision history: View changes and revert to earlier versions if needed.
• Deletion options: Remove outdated or unnecessary content as your project evolves.

Publishing Code as a Wiki

For projects that require a tighter integration between documentation and development, publishing code as a wiki might be the ideal solution. This approach involves transforming a collection of Markdown files stored in your repository into an intuitive wiki. It is common practice to keep these files in the same repository as your project code, ensuring that documentation is closely aligned with code changes.

Benefits of a Published Code Wiki

Publishing code as a wiki provides several advantages:

• Enhanced Organization: Create a clear hierarchical structure for your content.
• Efficient Browsing: Easily navigate and filter the table of contents.
• Synchronized Releases: Publish new versions of documentation alongside code releases.
• Version Control: Manage your documentation with familiar version control and review processes.
• Quick Search: Utilize powerful search features to retrieve the information you need swiftly.

By leveraging the features offered by Azure Wikis, you can create comprehensive and dynamic documentation that evolves seamlessly with your project. This improves collaboration and ensures that all team members have access to up-to-date project information.

Thank you for reading!