Technical writer and UX writer
GITHUB LABS
Spearheading the documentation efforts for Ephesoft Labs: a marketplace for scripts and plugins.
Role: Lead writer
Tools: GitHub, Google Docs, Confluence, Jira, Asana
Skills: Technical writing and editing, Markdown
Team size: 2
Timeline: 3 weeks
Outcome: Published all README files to GitHub
⚠️
CHALLENGE
We were requested to to assist with documentation for a new initiative at Ephesoft: a marketplace hosted on GitHub called Ephesoft Labs.
💡
SOLUTION
Create README files for ten private and public repositories in less than three weeks.
💬
PROCESS
1. Scoping and splitting efforts
Another technical writer and I met with product and SMEs to determine the scope of what should be included in the documentation.
Once we had this information, we met separately to distribute tasks and repositories based on any competing priorities.
2. Researching best practices
As the company's first venture into a public-facing marketplace on GitHub, we heavily researched README file best practices and familiarized ourselves with the repositories of strong performers on GitHub, such as Google and Microsoft.
3. Creating templates
To ensure our READMEs were structured in a predictable format and to streamline the process going forwards, we decided we needed templates.
This was organized and tracked in Jira for visibility.
We created README file templates for each type of repository. This is the template for integration-type repositories:
4. First drafts
Initial drafts were authored in Google Docs for easy sharing and review. We also wanted to keep the number of commits on each repository relatively low prior to the launch.
Content came from developer drafts and SME interviews.
Due to the relatively short time frame, we had to complete the initial drafts in less than a week. This allowed us to maximize our time for iterating.
5. Review and iterations
We met up independently with our SMEs for each repository to review and fine-tune the content through our iterations. Quick questions were simple to resolve using the commenting system in Google Docs, but most of our review was done over video conferencing using Zoom.
We also attended biweekly check-in meetings with team members and stakeholders to provide updates on our progress leading up to the release.
Here's an excerpt from a README file for a new plugin:
6. Publish
Once all files were reviewed and accepted by SMEs and stakeholders, we translated the content from Google Docs to Markdown and added them to GitHub.
✔️
IMPLEMENTATION
We published all ten README files to GitHub in time for the scheduled release.