Maker Pro
Maker Pro

Advice on setting up realistic documentation standards for a student club

I'm part of a FSAE team at my university and I'm looking to make function just like an engineering firm would. (Tips on that unrelated to my question are appreciated too) Since we're going to begin designing soon I'd like to set up a documentation format that is similar to that found in the industry. To make sure I'm understood, if someone is going to set out designing a widget what should they write down and how should it be formatted?
Thank you
 

Harald Kapp

Moderator
Moderator
Have you read the general information on software dosumentation available e.g. on Wikipedia?
You ned to distinguish between the development documentation (what is required to understand the code?) and the user documentation (what is required to use the software?).
My guess is you are into the former, development documentation.
It starts with describing the requirements aka use cases, followed by the software architecture to fulfill these requirements. The code itself should be well commented (not the obvious stuff, the one that needs explaining). A document that describes how the program wokrs rounds up these efforts.
It is also possible to generate documentation from the comments in the code - which need to be formatted accordingly - by using documentation generators. Under the premise that the comments are suitably accurate and up to date (updated with every change in code) these generators have the advantage that the resulting documentation is always up to dat, too.

It also helps to set up a few rules in advance to ensure a consistent and readable programming style, so called coding conventions. You could set up a style guide for these and hand it out to your students.

Here are a few links to get you going:
https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f
https://www.nickelled.com/software-documentation/
As it says here: https://www.smartics.eu/confluence/display/PDAC1/How+to+document+a+Software+Development+Project
There is no one-soze-fis-all approach. You'll have to find a way you and last not least your students are comfortable with. Be aware that as so often you'll get as many expert opinions on this topc as there are programming languages - plus one ;)
 
Top