Documentation on Gitlab

We utilize Gitlab's built in wiki feature to host markdown files natively in browser. Previous teams stored documentation in README.md files in the repository directory. While this approach is good for having documentation near the source code, It make searching the documentation more difficult. Moving the documentation to the Gitlab wiki, allows for the separation of source code from documentation, improving searchability.

Also note the wiki has been included in the main repo as a submodule, under the wiki folder. In order to clone it run git submodule update --init.

Organization

We will be using the top-level README.md as our main page for a brief introduction and as a link to the Gitlab wiki. You might notice that this page is automatically rendered on our main Gitlab project page.

Important documentation, such as getting started guides, and a general documentation outline should be linked directly on this page.

For documentation that is whole-project encompassing, They are place in the root directory of the wiki. For documentation that is sub-topic specific (firmware, ground station, test stand) they are to be place in their respective wiki directories.

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 the pencil icon 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.

To create a new file within the wiki, go to the "wiki" tab and then select the "New page" button in the upper right. From here, you can create a new Markdown file. Note, to place a page under a directory in the wiki, specify the path in the page title: path/to/page/page title

Linking

Linking to other wiki pages is easy. Simply surround the link text with square brackets [This is my link text] then directly follow it with the absolute or relative link in parentheses,

[absolute link test](https://www.google.com/) absolute link test

[relative link test](/Home) relative link test

Linking from the wiki to files in the main repository is a little more tricky, It technically isn't supported by Gitlab anymore (see discussion), however there is a work around.

When linking to a file in the repository, the relative link will look like this, /../blob/master/<path to file in repo> . However this method fails if there is a period anywhere within the path (likely caused by how Gitlab parses relative links in a wiki). So to work around this, replace any period with the ASCII equivalent %2E. The browser will convert this back to a period and go to the correct address.

Ex: /../blob/master/crazyflie_software/crazyflie-firmware-2021.06/.github/workflows/CI.yml

Becomes: /../blob/master/crazyflie_software/crazyflie-firmware-2021%2E06/%2Egithub/workflows/CI%2Eyml

Example Repo Link

Note that this work around only works on the web, These links will not work on local copies of the wiki.

References

At the bottom of each wiki page, it is useful to have a references section to link to external resources for further reading or additional troubleshooting avenues. This condenses the sources that were used to write that given wiki page.

If you create a new page make sure to include this at the bottom to follow the format and keep things consistent.

How to Write Documentation

(Originally written By Dr. Jones #24 (closed))

I've been going through the repository looking through the documentation, and wanted to give my feedback on things that will help with the transition to next years team. The goal being to capture your current experience to help lower the learning curve for next years team. This documentation effort can make the difference between next years team hitting the road running, and getting bogged down with trying to understand what you did and why you did it the way you did it.

1. MicroCART Quick Start Guide

Hello this year's MicroCART team! This guide is meant to get you up and going with performing test flights and plotting flight data quickly.

This documentation should be the first thing next years team reads to replicate your Senior Design demos. The current how_to_demo.md appears to be a start on this. It should have:

A welcome message with a short overview of the goal over you team's goals
- Which GIT tag should they be referencing for this document
How to run demos (perhaps this is a link to an extened how_to_demo.md)
- Link to video of some of the demos would be a nice to have.
How to plot test flight data (again perhaps a link to the extended how_to_demo.md)
How to run Matlab/Simulink model of the quad. Perhaps this is linked to so some type of how_to_demo_math_model.md

If for the Quick Start Guide, one wants to mostly leverage extending the how_to_demo.md, then it should have the following added:

More screenshots throughout the document
Information on the GUI
Setup information for three types of demos
- VRPN camera data as pseudo GPS
- VRPN camera data or (X,Y) GPS and Lidar for Z information
- Optical-flow for (X,Y), and Lidar for Z information
Plotting flight data

2. MicroCART Demo Directory

I noticed the team had an SD card for the VRPN camera quad demo, and one for the Optical-flow demo. It is great to have these, but in addition please add a /Demo directory that looks something like this.

/Demo
  /VRPN-XYZ-Demo
    README.md  BOOT.bin
  /VRPN-XY-Lidar-Z-Demo
    README.md  BOOT.bin
  /OpticalFlow-XY-Lidar-Z-Demo
    README.md  BOOT.bin

Each README.md would have

Description of what the demo does
How to build the BOOT.bin from the source code
Any modifications that need to be made to the source (e.g. adding/removing #if's or adding/removing comments)
How to run the demo (perhaps this just points to how_to_demo.md)

3. Test the final GIT tag

It is important that you test that things in your final tag actually work. This would involve

Do a fresh checkout/pull/clone (whatever the proper term is) of the tag
Compile all the source:

Virtual Quad code
Actual Quad code
Groundstation code
- Backend
- CLI
- GUI
ESP8266 code
Quad VHDL (i.e. FPGA hardware)

Run the code (for example run demos, with plotting of flight demo)
Test that all the MatLab/Simulik code works.

Note it is true that the Continuous Integration process should be putting your code base in pretty good shape, but it is important that you actually test that a fresh download your final tag actually works. As this is where next years team will start from.

4. More detailed feedback

This is section is in progress, as I have a number of detail comments I'm writing up. But I did want to point out a few nice pieces of documentation I came across in your repo:

how_to_use_xilinx_tools: This is pretty close to what I would call the ideal documentation one would want to handoff to a following team for a given topic.
Data_Analysis_Tool_Overview: Great screen shots with directions, great concrete usage examples, and gives a list of potential improvements at the end.
GUI_Guide: Again great screen shoots within the directions, and a list of limitations at the end.
zybo_pinout_assignments: This is pretty nice, hopefull it is called out from some higher level documents.
how_to_charge_lipo: Pretty nice, may need to be updated for the new batteries

One thing that is missing from these is the PowerPoint/Word/etc. source, so that future teams can easily update these documents.

A couple other quick comments:

The Quad Application README looks to be coming along nicely. Perhaps some of the above examples can be used for further inspiration for this and its sub-links that are under development.
Looks like the GroundStation documentation is under development
Looks like the Controls documentation needs to be brought together

The following feedback is broken into Quad, Ground Station, and Controls. But some of the comments are applicable to all three.

4.1 Quad

General Documenting/Commenting of Concepts/Code: A common pitfall I have observed by people with expertise on a given project is that when documentation is created unconsciously underlying assumptions are made, which make the documentation much less useful to someone new to a project. The following structure/mindset below can help avoid this pitfall:

Give an overview of the Concept or Purpose of code block
Give a simple concrete example
If applicable, show how code can be extended (e.g. adding a new GroundStation to Quad command)
If applicable, show how code/concept fits into the bigger picture of the project

1.1 README.md Example: Here is one example from Basic Testing Suite in C. The README.md files is done very nicely, and follows the above structure pretty well. I would suggest adding the following:
Show the expect output of running make test for the example

Walk through an example in the MicroCART project. I would suggest computation_graph. Something like.

/* Go to directory to run unit tests for computation_graph */
cd /MicroCART/quad/src/computation_graph

/* Run the unit tests */
make test   /* Tests run are found in computation_graph/test/test_computation_graph.c */

/* Show expected output */
...

1.2 Commenting Example: Here is an example for improving comments using the recommended general structure applied to test.h

...
#define TEST(name) test(name, #name)
...
void test(int (*)(), char *);
...

In general it is a good idea to have comments for macros and function prototypes. This is more so the case when using fairly advanced syntax. In this case a macro with a # parameter, and a function prototype that has a function pointer as an input. I would suggest these types of updates

```cpp
...
//Description: Macro to make calling tests look cleaner
// Note: #name substitutes a C-string constant corresponding to "name"
// Example:
// TEST(my_unit_test) will be converted into test(my_unit_test, "my_unit_test") 
#define TEST(name) test(name, #name)
...
//Description: Runs a specified unit test
//Inputs:
// int (*)(): A pointer to a function that returns an int and takes no input
// char *: A C-string that is typically the name of the function being pointed to.  See TEST macro above
void test(int (*)(), char *);
...


For this example of [test.h](https://git.ece.iastate.edu/danc/MicroCART/blob/master/quad/src/test/test.h), having the other elements similarly commented would be good. Along with the corresponding [test.c](https://git.ece.iastate.edu/danc/MicroCART/blob/master/quad/src/test/test.c), which includes a `fork`, which is a somewhat advanced system call, that I believe is being used to allow tests to continue to run even if they cause a `SEGV`. As much as possible, it would be good to go through the MicroCART code to strengthen the documentation/commenting using this recommended structure/mindset.

```plaintext
1.3 ...

In Progress

2.1 ...
2.2 ...
In Progress

4.2 Ground Station (In Progress)

4.3 Controls (In Progress)

Introduction to what's in the the /controls directory.: The README.md of the controls directory would be a good place to give:

An overview of the goals of the controls sub-team
An overview of the concepts that the control sub-team worked on
What components are found in sub-directories
Some type of figure(s) the show the big picture of how the control peices fit together

Data/Parameter collection: I was looking on the team's website and it looks like you have a good start on a number of documents. You will want to make sure these make it into the GIT (along with the source so that they can be updated by others). These documents appear to be mostly related to collecting data for the model. For example:

Characterizing IMU Sensor Data
Measuring Motor Resistance
Thrust and Drag Constant Measuring Procedure
I did not notice a document for Moment of Inertia measurement

Things that will be highly useful to be in these documents in addition to the write up text are:
A photo(s) of the setup so that one can see what they are working toward and can easily identify things in the lab that will be used and what end setup will look like.
Data that was collected, so that one can reproduce your results or compare against your results

Model: I don't think I've come across documentation of the model. Having a README.md in the /model directory would be a good place to give an overview of the model.
Things about the model that would be useful to document:

3.1 High-level model organization

3.2 How to run the model:
- Screen shots of what the model looks like in Simulink
- Examples screen shots of what results of the model should give when run out of the box, to help others verify if they are running your model correctly
3.3 Pointer to references: if one needs to get more detail on the theory of how an aspect of the model works or to better follow what you Matlab code is doing.

3.4 How to test components of the model: A description of how to verify different parts of the model in Matlab and/or Simulink.

Comments

Please register or sign in to add a comment.

How to Document Things on Gitlab