Our great sponsors
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
I would suggest introducing two things.
First, introduce The Diataxis framework ( https://diataxis.fr/ ) for documentation. It makes people think about documentation in a more structured way, and allows you to be more specific in the types of missing documentation. (High documentation cultures are often good with explanation but not tutorials, for example.)
Second, I would introduct the idea of a Documentation Portfolio. I have a review of Agile Documentation at https://www.ebiester.com/documentation/2020/06/02/agile-docu... and it speaks to another structure for how to build the documentation in a more reliable form and thinking more carefully about your audience for a particular type of documentation.
We use Mark[1] to automatically create Confluence pages from Markdown documents in our git repos. So we can have a review process for documentation changes, the documentation of the code can be in the repo with the code, and yet it can still be accessed without having to give permissions to view the code repo! Helpful with a proprietary monorepo.
Hadn't heard of this before, looks very cool. For anyone interested: https://github.com/claudioc/jingo
It's what we use, but there are two big show-stoppers to make it more user-friendly:
- the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup.
- can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much)
GitLab team member here.
Sharing a personal insight - I'm currently moving flats in the Nuremberg area in Germany which is a little hectic because forced out by the new house flat owner. Async work enables me to take calls and go shopping to organize the move, whilst shifting work hours into the evening or early morning. I am also able to take paid time off (PTO) when needed to prepare the move early December. In my previous office job, I would have needed to reserve a lot of vacation days for this, and ask for permission to start later than 10am, or after 4pm. Here at GitLab, I am my own manager [0] and take care about my working hours - it is a personal freedom, and I appreciate these less stressful times a lot. In return, I can take time to focus on private life, and come back refreshed to produce great results (blog posts, talks, helpful replies here and other community channels, etc.).
What I learned in the past 2 years and 9 months at GitLab, is to provide as much context as needed so that someone else in a different timezone can continue async, and is not blocked by anything (low context communication [1]). Also, short toes [2] enable everyone to add their thoughts and opinions, and work with the directly individual responsible (DRI) for the best outcome.
The Slack retention period of 90 days is a great reminder (and also enforcement) to document everything in the handbook. Example from today: I learned that Google docs supports the colon for emoji live-search. Thought of sharing in Slack, but then went with editing the handbook and sending a MR [3] to help everyone find this little efficiency tip in the future - that said, Slack is not a knowledge base. The GitLab handbook is.
Thinking about the past year with a public discussion about speaker diversity at events, I admire our teams to take action to ensure events align with our diversity, inclusion and belonging values. We have updated our event requirements for speakers (MR [4], handbook page [5]), and are working with event organizers and the wider community to help with mentoring and coaching to inspire future speakers.
Last but not least, transparency [6]. Internal and external, I can read and learn async at my own pace. Most of my meetings are optional, and the meeting notes/recording are detailed, with follow-up actions. You'll never recap old meeting notes the next time but reference actioned issues and merge requests. Many issues/epics are public - if you'd like to learn more about my thought leadership strategy for Observability, and all content created and planned, you can follow this epic [7] or my profile activity [8] for example.
I haven't met everyone in-person yet, because of the pandemic, and travel only for some events (KubeCon EU/NA, PromCon EU [9] [10]), but I am looking forward to meet and value these moments. Hard to describe, I feel incredibly connected to my teams albeit living far far away. :-)
Happy to share more thoughts and insights - my role is on the community relations/developer evangelism team, I'm the stable counterpart for the product teams, and collaborate in cross-functional initiatives often. [11] My first [12] and second [13] year blog posts share more experiences too :-)
[0] https://about.gitlab.com/handbook/leadership/#managers-of-on...
[1] https://about.gitlab.com/handbook/communication/#effective-c...
[2] https://about.gitlab.com/handbook/values/#short-toes
[3] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request...
[4] https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_request...
[5] https://about.gitlab.com/handbook/marketing/corporate-market...
[6] https://about.gitlab.com/handbook/values/#transparency
[7] https://gitlab.com/groups/gitlab-com/marketing/-/epics/2593
[8] https://gitlab.com/dnsmichi
[9] https://dnsmichi.at/2022/06/13/my-kubecon-eu-experience-firs...
[10] https://opsindev.news/archive/2022-11-23/#promcon-eu
[11] https://about.gitlab.com/handbook/marketing/community-relati...
[12] https://dnsmichi.at/2021/03/02/my-1st-year-all-remote-at-git...
[13] https://dnsmichi.at/2022/03/02/2-years-all-remote-and-2022-v...