Connect with us

Advice on setting up realistic documentation standards for a student club

Discussion in 'General Electronics Discussion' started by Braeden Hamson, Jan 16, 2020.

Scroll to continue with content
  1. Braeden Hamson

    Braeden Hamson

    220
    13
    Feb 18, 2016
    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
     
  2. Harald Kapp

    Harald Kapp Moderator Moderator

    9,632
    2,013
    Nov 17, 2011
    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 ;)
     
Ask a Question
Want to reply to this thread or ask your own question?
You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.
Electronics Point Logo
Continue to site
Quote of the day

-