The Static Site Editor Team is part of the Dev Section and is responsible for enhancing the editing experience for static sites inside of GitLab.
The following people are permanent members of the Handbook Team:
|Jean du Plessis||Backend Engineering Manager, Create:Static Site Editor|
|Derek Knox||Senior Frontend Engineer, Create:Static Site Editor|
|Jacques Erasmus||Senior Frontend Engineer, Create:Static Site Editor|
|Enrique Alcántara||Senior Frontend Engineer, Create:Static Site Editor|
|Chad Woolley||Senior Backend Engineer, Create:Static Site Editor|
|Vasilii Iakliushin||Senior Backend Engineer, Create:Static Site Editor|
The following members of other functional teams are our stable counterparts:
|Marcia Ramos||Senior Technical Writer, Create (Source Code, Knowledge, Static Site Editor, Editor)|
|Marcel van Remmerden||Product Design Manager, Create|
|Katherine Okpara||UX Researcher, Create|
|James Ramsay||Group Manager, Product Management, Create|
|Eric Schurter||Senior Product Manager, Create:Static Site Editor|
|Evan Read||Senior Technical Writer, Create (Gitaly, Gitter)|
|Michael Le||Senior Product Designer, Create:Static Site Editor|
|Darva Satcher||Senior Manager, Engineering, Create (Interim)|
|Mike Lewis||Staff Technical Writer, Create (Ecosystem)|
Depending on the context here are the most appropriate ways to reach out to the Static Site Editor group:
The team works primarily on the two projects listed below:
The work in the GitLab Handbook site is primarily focused on:
See the GitLab Handbook strategy for more information. Have a look at this epic to track the improvement efforts in the handbook: https://gitlab.com/groups/gitlab-com/-/epics/423
The handbook is currently part of the larger about.gitlab.com website repository which in addition to the handbook includes the marketing website, blog, jobs etc.
The repository is undergoing a refactor into a monorepo structure and the handbook will be split out into its own project. Progress can be followed here: https://gitlab.com/groups/gitlab-com/-/epics/282
The Static Site Editor engineering team develops and maintains the GitLab Docs project.
Work is tracked on our Development Workflow board which can be viewed here: https://gitlab.com/gitlab-org/gitlab-docs/-/boards/1668857
workflow::planning breakdownlabel to it.
workflow::planning breakdownand if determined that it is ready for implementation assign the
workflow::ready for developmentlabel to it.
Deliverablelabel to it.
Deliverablesfor a milestone are free to choose issues from the backlog (i.e. in
workflow::ready for development) to work on. Issues will always be listed in priority order from top to bottom on the workflow board.
The Static Site Editor group has two weekly group calls (agenda):
These two calls allow the majority of the team members to attend the relevant discipline focused call. Attendance is optional, but we encourage all team members to catch up on the recording of both meetings each week.
We also have a bi-weekly retro call on a Friday at 13:00 UTC.
We operate using async communication by default. There are times when a sync discussion can be beneficial and we encourage team members to schedule sync calls with the required team members as needed.
When scheduling a sync call do the following:
The group has a shared calendar called
Static Site Editor Group (email@example.com) where all group relevant meetings are shared on as well as team member PTO (refer to PTO Ninja below).
In general, we use the standard GitLab engineering workflow. To get in touch
with the Create:Static Site Editor team, it's best to create an issue in the relevant project
(typically GitLab or www-gitlab-com) and add the
~"group::static site editor" labels, along with any other
appropriate labels. Then, feel free to ping the relevant Product Manager and/or
Engineering Manager as listed above.
For more urgent items, feel free to use #g_create_static_site_editor on Slack.
In the Static Site Editor group we use epics to plan out our category maturity roadmap and the user stories in it.
The Static Site Editor category strategy epic can be viewed here: https://gitlab.com/groups/gitlab-org/-/epics/2688
The following tree structure indicates the epic and issue hierarchy we follow for the feature development of our maturity roadmap:
└── category strategy epic └── maturity level epic └── user story epic └── feature issue └── implementation issue └── implementation MR
We use the concept of parent/child issues to track a feature (parent) issue's progress independently from the implementation (child) issues. During the feature issue planning process the DRI will identify the various implementation issues that will be needed to deliver on the requirements.
These implementation issues will be created and linked to the feature issue as a blocker for the feature issue. This allows multiple team members to work on a feature issue, with each one assigned as the DRI for their own implementation issue.
Implementation issues progress through the workflow stages independently from the feature issue.
|Maturity level epic||Product Manager|
|User story epic||Product Manager|
|Feature issue||Product Manager|
|Implementation issue||Feature issue DRI|
Remove YAML front matter from editable content in the Static Site Editor
::syntax. Feel free to abbreviate "Static Site Editor" with SSE in the implementation issue.
Remove YAML front matter from editable content in the SSE::Sync model in component
The engineering team undertakes technical planning for each user story epic. Due to our iteration value we keep our planning process light, with the main aim of providing clarity around requirements and a high-level technical solution.
The expectation of the planning process is that by the end of it we:
The creation of user story epics, its validation and the creation of design mockups is an ongoing process that is not tied to a specific milestone. There could be many epics being worked on at any single point in time.
To encourage focus and not to overwhelm the engineering team with multiple priorities, planning on user story epics will focus on one epic at a time, in priority order as determined by the Product Manager.
During milestone planning the PM and EM will identify which features we are targeting to deliver during a specific milestone. Once finalized the EM will assign the feature issues to an engineer to drive implementation.
Once assigned the engineer becomes the DRI for planning and coordinating the implementation of the feature issue.
Feature issue planning can happen at any point in time, however, ideally all feature issue planning should be completed in the week before the milestone starts.
The status of implementation issues is reviewed in every group call.
Engineers are responsible for updating the status of all issues labeled with the
Deliverable label weekly on a Monday, before the group sync call.
If the status is anything other than
On track it should be accompanied by a comment in the issue that provides context on the status.
To be consistent with our status definitions the following guideline should be used when setting the status.
On track= on track to make it into milestone, meaning it will hit the gitlab.com production site before or on the 17th of the month. Ideally all deliverables should be merged by 16th. If MRs for backfilling tests or documentation won't make it into the milestone create a separate issue for it.
Needs attention= where either requirements clarification, additional engineering support or EM/PM intervention is needed to get it back on track to make it into the milestone.
At risk= where an issue is unlikely to make the milestone even if it receives attention.
The Static Site Editor group does NOT make use of weights to rigidly plan capacity or track velocity. Rather a continuous delivery mentality is adopted, facilitated through using a Kanban-style work management approach to moving work through the product workflow process.
The primary source for things to work on are the development workflow boards:
Deliverables are considered top priority and are expected to be done by the end of the iteration cycle in time for the release on the 22nd. To make it into the release in time it has to be merged and deployed to production by the 17th of the month.
These top priority issues are assigned to engineers by the Engineering Manager before the milestone begins.
Many things can happen that can result in a deliverable not actually being completed by the end of a milestone, and while this usually indicates that the Engineering Manager was too optimistic in their estimation of the issue's complexity, or that an engineer's other responsibilities ended up taking up more time than expected, this should never come as a surprise to the Engineering Manager.
The sooner this potential outcome is anticipated and communicated, the more time there is to see if anything can be done to prevent it, like reducing the scope of the deliverable, or finding a different engineer who may have more time to finish a deliverable that hasn't been started yet.
If this outcome cannot be averted and the deliverable ends up missing the milestone, it will simply be moved to the next milestone to be finished up, and the engineer and Engineering Manager will have a chance to retrospect and learn from what happened.
Generally, your deliverables are expected to take up about 75% of the time you spend working in a month. The other 25% is set aside for other responsibilities (code review, community merge request coaching, helping people out in Slack, participating in discussions in issues, etc), as well as urgent issues that come up during the month and need someone working on them immediately (regressions, security issues, customer issues, etc).
If you have time to spare after finishing your deliverables and other
activities, you can pick any issue that is ready for development
(i.e. is in the
workflow::ready for development column).
The issues in this column are ordered by priority so choosing from the top of the list is recommended.
If anything is blocking you from getting started with the top issue immediately, like unanswered questions or unclear requirements, you can skip it and consider a lower priority issue, as long as you put your findings and questions in the issue, so that the next engineer who comes around may find it in a better state.
Instead of picking up an issue from the Handbook or Static Site Editor boards, you may also choose to spend any spare time working on anything else that you believe will have a significant positive impact on the product or the company in general. As the general guidelines state, "we recognize that inspiration is perishable, so if you’re enthusiastic about something that generates great results in relatively little time feel free to work on that."
We expect people to be managers of one and prefer responsibility over rigidity, so there's no need to ask for permission if you decide to work on something that's not on the issue board, but please keep your other responsibilities in mind, and make sure that there is an issue, you are assigned to it, and consider sharing it in #g_create_static_site_editor.
The easiest way for engineering managers, product managers, and other stakeholders to get a high-level overview of the status of all issues in the current milestone, or all issues assigned to specific person, is through the Development Workflow boards, which has columns for each of the workflow labels described on Engineering Workflow handbook page under Updating Issues Throughout Development.
As owners of the issues assigned to them, engineers are expected to keep the workflow labels on their issues up to date, either by manually assigning the new label, or by dragging the issue from one column on the board to the next.
When creating an issue that relates to our group make sure to always add the following labels:
group::static site editor
Category:Static Site Editorfor issues relating to the product we are building
Category:GitLab Handbookfor issues relating to work we are doing on the GitLab Handbook in gitlab-com/www-gitlab-com
backend) if relevant to indicate which disciplines will need to be involved in actioning the issue.
The EM and PM is responsible for setting any other relevant labels and milestones on the issues.
All MRs¹ should contain the following labels to accurately reflect in our metrics dashboard:
group::static site editor
feature- when introducting new or updated functionality
bug- when fixing a bug
backstage- when doing behind the scenes work.
security- when fixing a security vulnerability
¹ Exception for
gitlab-com/www-gitlab-com repo: Content related MRs (think fixing a spelling mistake, updating the info on the team page etc) should not contain the group label as it should not count towards our throughput.
These guidelines extend the team collaboration guidelines documented in the Engineering workflow page.
Some deliverables have frontend and backend components. For those cases, the backend and frontend engineers should coordinate in advance the data contract expectations between both parts of the stack and document those expectations in the deliverable’s issue. These are examples of data contracts that team members can agree in advance:
This initial plan does not replace communication during the development process. The engineers involved in the development of a feature should continuously communicate the status of their work.
You should strive for receiving feedback early and often in your Merge Requests. If your Merge Request delivers frontend work that depends on unfulfilled backend requirements, demo your work using mock data based on the data contract expectations defined at the beginning of the development process.
For example, you can prepopulate a VueX store or a VueApollo cache with initial data to demo a feature that introduces read-only enhancements. You can also simulate HTTP responses in your Vuex actions to demo a workflow that mutates data.
If you are working on a backend Merge Request, it is a good practice to request feedback from your Frontend engineer counterpart. After all, the Frontend engineer will be the main user of your work.
If a deliverable has backend and frontend components, develop those components behind a feature flag. Once all the components are merged into master, create a Merge Request that:
Do not add a changelog entry in your Merge Requests if your work is hidden behind a feature flag.
We use workflow labels to identify the current stage of a deliverable. Use the following guidelines to assign a workflow label:
~workflow::in devonce you have started to work on a deliverable.
~workflow::in reviewonce all the tasks required to complete a deliverable are under review.
~workflow::verificationwhen the deliverable is demonstrable on production.
When multiple contributors are assigned to an issue:
@handleis appended to their task item(s) to convey explicit ownership
When a single contributor is assigned to an issue all tasks are implied to be owned by the issue owner.
Inline with GitLab's code review guidelines we default to assigning the first review to a team member. This not only ensures that team members are up-to-date with changes to the product, but facilitates a faster review turn-around.
When assigning an MR to a maintainer, default to a team member (if there is someone other than yourself), to ensure fastest possible turn-around.
While GitLab's current Review-response SLO is 2 business days, we aim for 1 business day for internal team reviews.
For trivial MRs feel free to assign to any GitLab team member, defaulting to the recommendation from Reviewer Roulette.
The goal is to support the members of these groups in connecting at a personal level, not to check in on people's progress or replace any existing processes to communicate status or ask for help, and the questions are written with that in mind:
We use issues to facilitate an async retrospective process for each milestone.
Career development conversations in the Create:Static Site Editor BE team are centered around a Career Development Sheet that is based on the Engineering Career Matrix for Individual Contributors. The sheet lists the expected current level behaviors on the left, the next level behaviors on the right, and uses colored columns in between to visually represent the extent to which the individual has shown to have grown from the current level to the next. Columns to the right of a next level behavior are used to collect specific examples of that behavior, which serve as evidence of the individual's growth.
Both the matrix and the sheet are Works in Progress; the development of the career matrix is tracked in an epic, and as the matrix evolves, the sheet will be updated to match.
New team members to the Static Site Editor group can use the resources below, in addition to their general onboarding, to get up to speed.
|Product Section Direction - Dev||Read the Product Direction for the Dev section to get a better understanding of the area of the product that we fall into|
|Category Direction - Static Site Editor||Read the Static Site Editor category direction to understand more about the product we are developing|
|Static Site Editor Group Call Agenda||Read the notes from our past group calls and watch the recordings to get an idea of what we discuss in our weekly sync call. Recording links are provided below each date heading and you can view the full list of recordings here in Google Drive|
|🧠 Think Big : Static Site Editor||We hold Think Big sessions to explore where we might want to take our category in the future. These sessions help inform what our vision looks like and the roadmap we take to getting there.|
|Static Site Editor Vision Braindump||If you're interested in all the various angles we explored in helping get to our current vision this document will give you some context. Note that its for context purposes only and not to be seen as a guide for what we will/wont do down the line.|
The following channels are important to be a part of:
The following Slack channels, while optional, are relevant to our group and you should consider joining them:
We use PTO Ninja to notify and delegate for planned timeoff. When setting up your integrations with Slack,
be sure to visit the PTO Ninja Home tab and choose the Calendar Sync option from the dropdown.
Then add the team's shared Google Calendar
firstname.lastname@example.org in the "Additional Calendar to include?".
As a new developer at GitLab you might find these command helpful with your day to day coding. View the Cheatsheet
We encourage pair programming not just as part of your onboarding into the team, but as a general good practice. Read our guideline on pair programming.
The EM is responsible for the OKRs of the Static Site Editor group.
Current OKRs can be viewed here: https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/7630
We use OKRs for team members to:
We do NOT use OKRs at team member level for any sort of performance measurement and we do not report on it publicly.
The main themes for Q2 are:
FY21 Q2 OKRs for the team members:
|Team Member||Objective||Key Results|
|Jacques Erasmus||Implement Learnings||A GraphQL feature improved or implemented in the product.|
|Improve Static Site Editor product||Image uploading|
|Overall styling alignment|
|Docs: Enable other GitLab team members to contribute easily||Modernize JS|
|GitLab UI integration|
|Enrique Alcantara||Implement Learnings||GraphQL API improved in the product|
|Become domain expert for GraphQL at GitLab|
|Improve Static Site Editor product||All REST API calls replaced with GraphQL API calls|
|Vasilii Iakliushin||Implement Learnings||A GraphQL API improvement landed in the product|
|Become domain expert for GraphQL at GitLab|
|Improve Static Site Editor product||All REST API calls replaced with GraphQL API calls|
|Derek Knox||Implement Learnings||GraphQL feature improved, implemented in the product|
|AST knowledge gained implemented in the product|
|Improve Static Site Editor product||Effective handling of front matter in our product|
|Handbook: Assist in creating separation of Handbook from wider www-gitlab-com project||Bundling (CSS + JS) - Rollup|
|Chad Woolley||Improve Static Site Editor product||Contribute first feature to the product|
|Handbook: Assist in creating separation of Handbook from wider www-gitlab-com project||Monorepo structure in place|
|Project specific pipelines in place|