diff --git a/documentation/how_to_document_things_on_gitlab.md b/documentation/how_to_document_things_on_gitlab.md index a776779e8aca0313afc5031890d4d12278d7953f..86e6fd1774048a3bc79bfe2b65c51544fc87daf3 100644 --- a/documentation/how_to_document_things_on_gitlab.md +++ b/documentation/how_to_document_things_on_gitlab.md @@ -1,4 +1,34 @@ # Documentation on Gitlab We can use Gitlab to host our documentation by exploiting the fact that Gitlab automatically renders Markdown (.md) files as HTML in the browser, making it -easy to read and show images. \ No newline at end of file +easy to read and show images. + +# Organization +We will be using the top-level `README.md` as our main page for documentation. +You might notice that this page is automatically rendered on our [main Gitlab +project page](/../). + +Ideally, all documentation should be reachable from links on this main page. +For documentation that is while-project encompassing, those links should go +on the main page itself. For documentation that is sub-topic specific (quad, +ground station, controls), add an appropriate link on the sub topic's README.md +page. See the Quad section for an example. + +Ideally, all Markdown (.md) files should go inside some `doc` or `documentation` +folder (with exception to the READMEs). + +# Editing +If you are familiar with Markdown and Git, you can just edit the documentation +from within your normal Git workflow. + +However, Gitlab also makes is relatively easy to edit Markdown pages for +documentation right in the browser. To edit a Markdown page, select "Edit" at +the top right. This will bring up an editor that you can use to make changes. +To preview the final project, use the "Preview" tab at the top left. To achieve +desired formatting, you will need to use the Markdown syntax - see the [Gitlab +Markdown reference](https://docs.gitlab.com/ee/user/markdown.html). + +To create a new file within Gitlab, go to the "Repository" tab and then "Files" +tab. As you navigate through our files, you will see a "+" (plus sign) button. +From here, you can create a new Markdown file, upload a new file, or create a +folder (say if you need to create some `doc` folder).