CERN-HSF project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
CERN-HSF
Technical writer:
SabitaR
Project name:
Restructuring & Streamlining of the Allpix Squared Documentation
Project length:
Standard length (3 months)

Project description

OVERVIEW I’ve chosen CERN-HSF’s Allpix Squared project for two main reasons:

  1. Skill building: This project's existing documentation is comprehensive and integrates multiple content formats. Auditing and restructuring this extensive doc suite will help me polish my info architecture and writing skills. Additionally, the project domain (particle physics!) is new to me. It challenges me to hone my developer interaction skills. I believe that technical writers can process inputs from developers and present useful content for any level of users, IF we do our required background research, and ask the right questions. This project will let me test this theory!

  2. Technical know-how: This project requires Hugo - a tool that features at the top of my to-learn list. I look forward to learning the LaTeX-Markdown-Hugo-GitLab-CI workflow.

During the technical writer exploration phase, I interacted with the project mentors briefly and familiarized myself with the existing doc suite structure. I also built a demo website (https://ap2-demo.netlify.app/) to test if I can configure Hugo and Docsy correctly on my Windows machine. I was able to deploy the website to Netlify but not to Gitlab Pages. For this project to maintain its current deployment workflow, I’ll find a way to deploy the Hugo Docsy theme to Gitlab Pages.

EXPECTED PROJECT RESULTS - A streamlined project website that integrates documentation, code reference, tutorials, and news. - A restructured and reviewed user manual which separates content intended for users and developers, and includes previously missing information. - A tutorials workflow from available examples of how-to documentation, FAQs, and commonly-faced issues.

PROJECT TOOLS Allpix Squared's current documentation uses LaTeX, Doxygen, pandoc, and Hugo, in addition to GitLab and Gitlab CI. The project mentors and I have chatted about possibly moving content from LaTeX to Markdown with MathJax plugins. If I succeed, the doc workflow will then involve Hugo, Markdown, Doxygen, git, and Gitlab CI. To keep tutorials within the same website/platform, I’ll use Hugo and Markdown. I’m curious about the feasibility of using Codelabs-as-a-Tool (ClaaT) for tutorials. This July, I hope to test the ClaaT-Hugo workflow and discuss it with the mentors, if selected.

PROJECT DURATION I’m requesting to complete the Allpix Squared project within the standard three-month period (Sept 14, 2020 - Nov 30, 2020), during which I will spend approx. 15 hours per week on it. These hours will include mentor meetings and related emails, as needed. I will adhere to the GSoD timelines for community bonding and project finalization too.

PROJECT TASKS Here’s how I intend to implement my proposed updates to the existing Allpix Squared doc suite: 1. Research, discuss and explore options (Aug 17 - Sep 13, 2020): - Understand the project requirements - Install the Allpix Squared software to identify missing info, if any, in the current docs. - Request the necessary credentials. - Create user workflows for different users of Allpix Squared - Classify content by user role - Check the implications of converting LaTeX files to Markdown - Consolidate source repositories or understand how to work with multiple git repositories - Bonus: Test CLaaT as an option for tutorials - Bonus: Author a quick style guide/shortcodes reference to help contributors maintain docs Timeline: Community bonding phase

  1. Restructure, review, and enhance the content (Sep 14 - Oct 19, 2020): Two tasks per week, approx 5-7 hours per task. This timeline includes a buffer week to handle unexpected delays or issues.

    • Review existing content and user classifications with user workflows in mind
    • Outline and test restructured content workflow for different users
    • Source and enhance missing content
    • Convert LaTeX files to Markdown
    • Finalize the user guide and developer guide table of contents
    • Generate PDFs of the user and developer guides
    • Bonus: Structure content for tutorials from examples and issues
    • Bonus: Setup a tutorial workflow for how-to examples Timeline: 5 weeks (Doc development phase)

  2. Build the website (Oct 19 - Nov 30, 2020): 1-2 tasks per week, approx 5-7 hours per task. This timeline includes a buffer week to troubleshoot issues and fine-tune the final output.

    • Understand and test the publishing workflow
    • Build a website structure using Hugo and Docsy
    • Test how to maintain the current automatic deployment and workflow using Docsy
    • Pull content from Doxygen
    • Develop user manual, developer guide, and tutorials from LaTex or Markdown content
    • Finalize the look and feel of the project website (logo, colors, template, layout, links, usability, and Gitlab CI/CD) Timeline: 6 weeks (Doc development phase)