CERN-HSF project
Stay organized with collections
Save and categorize content based on your preferences.
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:
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!
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
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)
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)
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\u003cp\u003eThis project aims to restructure and streamline the documentation for Allpix Squared, a CERN-HSF project, improving its user experience and accessibility.\u003c/p\u003e\n"],["\u003cp\u003eThe project will involve migrating content, potentially from LaTeX to Markdown, and reorganizing it into user-focused sections like user guides, developer guides, and tutorials.\u003c/p\u003e\n"],["\u003cp\u003eThe final deliverable will be a consolidated website built with Hugo and Docsy, featuring a streamlined information architecture and enhanced content, including tutorials and improved navigation.\u003c/p\u003e\n"],["\u003cp\u003eThe project will be conducted over three months, utilizing tools like Hugo, Markdown, Doxygen, Git, and GitLab CI, and will focus on creating a more user-friendly and comprehensive documentation experience for Allpix Squared.\u003c/p\u003e\n"],["\u003cp\u003eThe technical writer will leverage their skills in information architecture and technical writing to improve the documentation's overall structure and clarity.\u003c/p\u003e\n"]]],["The core of the project involves restructuring and streamlining the Allpix Squared documentation for the CERN-HSF open-source organization. Key actions include researching project requirements, installing the software, classifying content by user role, and converting LaTeX to Markdown. The technical writer will build a new website using Hugo and Docsy, integrating documentation, code references, and tutorials, while also restructuring the user manual and developer guide, with the aim of enhancing the project's overall accessibility. These will be made within the standard three-month period.\n"],null,["# CERN-HSF project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\n### Project summary\n\nOpen source organization:\n: CERN-HSF\n\nTechnical writer:\n: SabitaR\n\nProject name:\n: Restructuring \\& Streamlining of the Allpix Squared Documentation\n\nProject length:\n: Standard length (3 months)\n\n### Project description\n\nOVERVIEW\nI've chosen CERN-HSF's Allpix Squared project for two main reasons:\n\n1. Skill building:\n 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.\n 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!\n\n2. Technical know-how:\n 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.\n\nDuring 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.\n\nEXPECTED PROJECT RESULTS\n- A streamlined project website that integrates documentation, code reference, tutorials, and news.\n- A restructured and reviewed user manual which separates content intended for users and developers, and includes previously missing information.\n- A tutorials workflow from available examples of how-to documentation, FAQs, and commonly-faced issues.\n\nPROJECT TOOLS\nAllpix Squared's current documentation uses LaTeX, Doxygen, pandoc, and Hugo, in addition to GitLab and Gitlab CI.\nThe 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.\nTo 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.\n\nPROJECT DURATION\nI'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.\n\nPROJECT TASKS\nHere's how I intend to implement my proposed updates to the existing Allpix Squared doc suite:\n1. Research, discuss and explore options (Aug 17 - Sep 13, 2020):\n- Understand the project requirements\n- Install the Allpix Squared software to identify missing info, if any, in the current docs.\n- Request the necessary credentials.\n- Create user workflows for different users of Allpix Squared\n- Classify content by user role\n- Check the implications of converting LaTeX files to Markdown\n- Consolidate source repositories or understand how to work with multiple git repositories\n- Bonus: Test CLaaT as an option for tutorials\n- Bonus: Author a quick style guide/shortcodes reference to help contributors maintain docs\nTimeline: Community bonding phase\n\n1. Restructure, review, and enhance the content (Sep 14 - Oct 19, 2020):\n Two tasks per week, approx 5-7 hours per task. This timeline includes a buffer week to handle unexpected delays or issues.\n\n - Review existing content and user classifications with user workflows in mind\n - Outline and test restructured content workflow for different users\n - Source and enhance missing content\n - Convert LaTeX files to Markdown\n - Finalize the user guide and developer guide table of contents\n - Generate PDFs of the user and developer guides\n - Bonus: Structure content for tutorials from examples and issues\n - Bonus: Setup a tutorial workflow for how-to examples Timeline: 5 weeks (Doc development phase)\n2. Build the website (Oct 19 - Nov 30, 2020):\n 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.\n\n - Understand and test the publishing workflow\n - Build a website structure using Hugo and Docsy\n - Test how to maintain the current automatic deployment and workflow using Docsy\n - Pull content from Doxygen\n - Develop user manual, developer guide, and tutorials from LaTex or Markdown content\n - 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)"]]
