Skip to content

Documentation#

Rules and directions for documentation#

Why document#

The sole purpose of this initiative is to keep on the chain of knowledge intact. The founding members had suffered the break in the lineage and took around three years to develop from scratch and we aren't even halfway through. This documentation is important for every member of the club. This will provide the upcoming batches of members to learn and tackle issues related to the tasks. This will also help your peers to understand the tasks performed and analyze it to give any positive feedback. Most importantly, this repository will help the members to put up technical reports and it can provide a platform to showcase their work.

How to document#

There are very few docs that make us understand how, why and what to document. One of it is The documentation system — Documentation system documentation

overview
Source

A very good guide describing 'why documentations are required in coding?' can be found here: A beginner’s guide to writing documentation — Write the Docs.

An insightful guide for why and how to document your technical writings can be found here: What to write - Beginners Guide to docs - writethedocs.

What to document#

  1. Any novel procedure/technique used apart of previously documented work in the same field.
  2. Usage of new types of equipment/tools/software/boards that were not previously used and its usage had drastically improved the working of the vehicle.
  3. A new idea/concept that has been used for improving the efficiency and design of the vehicle. This idea may have been already proven by other teams but couldn't be completed under the team member's tenure in the club and he/she has to transfer this idea to the juniors.
  4. Any undocumented (significant) procedure that is used in the working of the vehicle.
  5. Any undocumented work that was previously left incomplete/missed by the seniors.
  6. Comparative studies - Survey of pros and cons of techniques or hardware/pieces of equipment, which will help in buying the best and efficient one.

What NOT to document#

  1. Those which do not have concrete evidence for the result.
  2. Redundant information that has already been done by previous members.

Format of docs#

The report must be in the format:

title: Title of the report

author(s): Name of the authors

email-id(s): Email id of all the authors

Objective: Main goal of the task or learning

Introduction: small theory of the techniques/equipment used for the task to be done

Equipments/Software used: Hardware used, software with its versions

Procedure: Write in simple terms which when replicated by any team member. Pointwise.

Results: if the work was completed OR expected result when the experiment couldn't be completed

Future work: what future steps can be taken to enhance your work

You can submit in .docx files to the team members or directly push to this repository.

Hierarchy of Submission#

  1. The docs have to be written in the above format and then submitted to their respective team heads.
  2. The team heads will attest to the completion of the work (OR IF NOT COMPLETED; he/she will give his witness about the experimentation performance).
  3. Compile all the docs from all the team members and submit them to the coordinator.
  4. The coordinator will upload it to the central repository.

Role of Team heads#

  1. Make sure that no two team members have written the same content.
  2. If it's a collaborated work; the contribution of each team member with equal effort has to be acknowledged.
  3. The content provided by the members does not resemble any previous work.

Role of the coordinator#

  1. Collect all the docs from each team head after rectification.
  2. Pull requests once the team head gives a green flag.
  3. Convert .docx files into markdown.
  4. Handle any discrepancies from the team members.
  5. Handle queries from any person trying to know about the content.
  6. Handle content from non-club members (Club alumni/experts).

Note

The coordinator must make sure that the documentation can be put in the public domain with the permission of the authors. If the material provided has been submitted for publishing a research paper, the docs must not be uploaded, as this may ruin the opportunity of the paper to be published. The paper when published, can be linked in the docs, later.

Teams#

The roles of various positions and documentation of tasks can be found in the respective teams' index page:

  1. Computer team

  2. Electrical/Electronics team

  3. Marketing team

  4. Mechanical team