Docs as Code has long been associated with developer-centric workflows, but the same principles can empower documentation teams. By integrating Docs as Code into internal processes, writers can collaborate on code samples, improve accuracy, and ensure consistency across documentation. This article outlines a strategy for enabling doc teams to maintain and share their code samples in a way that aligns with broader development workflows.
What you’ll need
A free GitHub account or a business account with an Organization set up.
Steps
1. Set up a shared repository for the team’s code samples.
This improves collaboration, consistency, and alignment with the development workflow.
This enables writers to:
- Update code samples based on the latest product features.
- Easily collaborate with developers and other writers.
- Ensure version control and a historical record of changes.
- Keep code organized when a writer’s assignment changes.
a. On your user profile, click Repositories on the toolbar.
b. Click New.
c. Fill out the Create a new repository form.
| Field | Description |
|---|---|
| Owner | Specifies who will own the repository. This may be a manager or project lead. |
| Repository name | Unique name of your repository. Choose a descriptive, meaningful name. Avoid spaces or special characters; use hyphens or underscores if needed. |
| Description | Short description of what your repository is for. |
| Public/Private | Visibility of your repository. Public: Anyone on the Internet can see the repository. However, only people with the appropriate permissions can make changes. This is ideal for open-source projects or repositories where you want the world to see the content. Private: Only you (and any collaborators you explicitly grant access to) can see and work on the repository. This option is ideal for internal projects, confidential code, or documentation that should only be visible to certain team members or collaborators. |
| Add a readme file | Contains the overview of your project, instructions for use, or other important information. A README file might contain installation instructions, usage examples, and links to further documentation. |
| Add .gitignore | Specifies which files or directories Git should ignore (i.e., not track) in the repository. |
| Choose a license | Defines how others can use, modify, and distribute your repository’s content. This is crucial, especially for open-source projects, as it protects your intellectual property and specifies how others can legally interact with your code or content. |
d. Click Create repository.
2. Set up a specific project according to doc needs.
The idea is to create modular projects that have a start, end, and smaller tasks that the broader task can be broken down into. The more specific the project, the better.
For example, a project could focus on a feature like Unified Navigation. Here, the start is the development of deliverables, and the end is the delivery of those deliverables. Within the project, list specific tasks related to creating documentation for Unified Navigation.
3. Create a Project Board.
This is a project management tool for organizing issues that connects directly to specific repositories. Issues can be created and assigned a repository and writer.
a. Click New View.
b. Select Board to access the Project Board view.
4. Create a new issue.
a. Click Add item.
b. Enter # followed by the name of the team repository. For example, #contracts.
c. Enter the name of the new issue.
5. Assign the issue to a writer.
a. Click the text of the new issue.
b. On the Issue page:
i. Click Assign yourself.
or
ii. Click Assignees and identify the person you want to assign the issue to.
c. Add a label that applies to the nature of the issue.
6. Implement a branching strategy.
A sound strategy may be one where your team members create a new branch for each feature or issue they are working on.
This allows for:
- Parallel development without interfering with others.
- A stable main branch where only reviewed and approved code samples are merged.
- Specific branches can be created for specific releases, enabling easier rollbacks, if needed.
a. In the main team repository, click Branch.
b. Click New Branch, and enter a name for the new branch.
c. Click Create new branch.
8. Set up a wiki for documentation standards and guidelines.
This content can be linked to from the team repository readme.
Include the following minimum sections:
- Style Guides: Create or adopt a style guide for code documentation to ensure consistency in language, formatting, and structure.
- Best Practices: Share best practices for writing clear, maintainable code samples, such as using meaningful variable names and including comments where necessary.
9. Create a Q&A Section.
Consider including a wiki section for common questions or misconceptions about implementing Docs as Code in documentation teams and the processes involved. This can clarify commonly asked questions and provide valuable guidance for the team.
Conclusion
By adopting Docs as Code, documentation teams can streamline their workflows, enhance collaboration with developers, and ensure consistency across projects. Integrating version control, project management, and collaboration tools like GitHub allows writers to maintain, update, and share code samples more effectively. Whether you’re part of a small team or a solo technical writer, implementing these practices can reduce errors, improve efficiency, and keep documentation aligned with product development.
Double Yew! 