Overview

This handbook is intended to be the central repository of process, knowledge, technique and culture for Roivant IT. It’s specifically intended for everyone in Roivant IT to be able to contribute and collaborate on the content. In support of a enabling distributed, asynchronous contributions from everyone, we are treating this documentation as code

CODE?!

Do not panic. We’re going to treat this content like code, you don’t need to actually write any code. For those of you very new to this, some of it may feel alien or confusing but not only will it become familiar very quickly, it’s almost all during setup and we’ll try to make this as simple as possible.

What about Confluence/Office Docs/Some other system?

Part of the goal is to use systems for what they are actually good at. “Docs-as-code” is very good at some things - Single-source-of-truth, editing by distributed teams, versioning whole sets of pages, bulk edits, custom layouts - things that are good for a collaboratively created “book”. It’s not good for taking meeting notes, for realtime multi-author editing, nor anything like spreadsheets or diagrams.

Do use O365 documents - in fact, use them a lot. Use them for material that updates constnatly, for quick notes, meeting agendas, meeting notes, for interfacing with outside teams - for what they’re good at. Some of the material you write might end up in the handbook, much of it simply doesn’t need to. Some of it can be linked to, or embedded in the handbook, if we need the best of both worlds.

How do I participate?

To start off, I’ll tell you what this handbook is composed of - all of which is very well documented on the web, and all of which you are free and encouraged to explore and learn. This handbook is made using:

• Markdown - a human-friendly, very lightweight markup language that can be turned into HTML without ever touching HTML.
• Hugo - A static site generator that turns markdown into a website.
• Git - A version control system that tracks changes to files (pages) and enables a group to collaboratively work on the content.
• GitLab - A hosted Git service with a rich set of features for distributed teams.
• VSCode - A robust text editor with markdown previews and tons of tools built in.
• Typora - A beautiful Markdown editor that makes authoring in Markdown even easier.

The absolute shortest path to small edits

At the top right of every page in this handbook, there is an “Edit this page” link. This will open any given page in GitLab’s Web IDE. It’s not the most user-friendly UI in the world, but it’s quick, immediate and easy to access. You’ll initially see plain-text Markdown, but there’s a “Preview” tab that will give you an idea of what it looks like. Make some edits, hit the blue “Commit” button, add your commit message and you’re done.

Setting up your handbook environment

For more complete, or larger scale editing - say you want to author an entire section about a team or product - you’ll want to set up a local authoring environment, edit the pages with Typora (or any editor you choose) and use Git to push your changes to GitLab.