Your docs
==========

The government forces us, respectively you to write a documentation / learning journal.

Most other companies force their trainees to do this the `classical` way. However, at this point you should know about :ref:`Shell Basics`, :ref:`Development Basics`, :ref:`Git` & :ref:`CI/CD Pipelines` and we can take a more modern approach.

We're using `Sphinx Docs <https://www.sphinx-doc.org/en/master/>`_ to build web-based documentations like these.

Please ping your coach and tell him he should help you to setup your own documentation.

.. note::

    Notes for the coach:

    - Have a look at the `Blueprints Docs <https://blueprints.confirm.ch/>`_
    - Explain the purpose of having `Blueprints <https://gitlab.confirm.ch/confirm/blueprints>`_ and how they work
    - Clone the `Documentation Blueprint <https://gitlab.confirm.ch/confirm/blueprints/documentation>`_
    - Clone the repository into the `Trainees Namespace <https://gitlab.confirm.ch/confirm/trainees>`_
    - Use the first name as cloned name (e.g. ``Thaddeus``), since ``-docs`` will automatically been added (e.g. ``thaddeus-docs``)
    - Update the `GitLabGuard <https://tools.confirm.ch/api/gitlab.html#confirm.tools.gitlab.GitLabGuard>`_ settings to make sure ``master`` is not protected
    - Update the Sphinx settings to point to the `Trainees Namespace`_

When everything is setup accordingly, do this:

- Make sure you can build the documentation locally (i.e. ``make docs``)
- Make sure you can run the auto builder (i.e. ``make autodocs``)
- Have a look at the CI/CD pipeline
- Have a look at the deployed live docs
- Understand how the deployment process works (broadly)
- Extend the documentation locally
- Commit the changes and see if they're deployed

.. todo::

    We might need to deactivate the `commit validation <https://gitlab.confirm.ch/confirm/gitlab-ci/-/tree/master/validate-commits>`_.

Guideline Weekly Report
-----------------------
To measure your achievements and assess your progress during this apprenticeship, you'll be documenting your journey on a weekly basis. This documentation will serve as a valuable tool for tracking your learning, addressing any questions or challenges you encounter, and setting clear objectives for your growth.

Each week, you'll record the tasks you've undertaken, your questions, the guidance you've received, and your overall progress. This process will not only help you stay on track but also ensure that your apprenticeship experience is both productive and enriching.

I. Overview
~~~~~~~~~~~

Tasks and Achievements
^^^^^^^^^^^^^^^^^^^^^^

- Provide an overview of the tasks and activities you've undertaken during the week.
- Highlight any significant milestones or accomplishments.

II. Trainee Questions
~~~~~~~~~~~~~~~~~~~~~
As part of your apprenticeship journey, it's essential to foster a culture of curiosity and continuous learning. To facilitate this process, we kindly ask you to document five questions about topics you have had during the week. You can use the following format as a guide:

Question N
^^^^^^^^^^

- **Date:** [Date]
- **Question:** [Your first question of the week]
- **Context:** [Context for the question, including the relevant task or situation]
- **Answer/Guidance:** [Record the response or guidance provided/requested]

III. Trainee Progress
~~~~~~~~~~~~~~~~~~~~~

Assessment
^^^^^^^^^^
- Provide a brief assessment of the trainee's overall progress during the week.
- Identify areas of excellence and improvements.
- Mention any challenges faced or areas requiring additional support.

IV. Next Steps
~~~~~~~~~~~~~~

Objectives and Tasks
^^^^^^^^^^^^^^^^^^^^
- Outline the objectives and tasks for the upcoming week.
- Specify areas of focus and skills development.
- Note any planned training sessions or resources for the trainee.