If car user handbooks were like software documentation ...

Go To Last Post
9 posts / 0 new
Author
Message
#1
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 1


 

A few years back, in another thread, I wrote:

The trouble I find with all this doxygen-generated "documentation" is that it just gives a very "close-in" view - there never seems to be any "overview" as to how stuff should be structured, etc.

 

(that may not be the fault of doxygen itself - but is certainly a fault with, I think, every usage I've seen)

 

https://www.avrfreaks.net/commen...

and today I saw the above photo, and thought yep, that's how too much software documentation looks:  a whole load of tiny pieces all laid out, described, and labelled - but nothing to tell you how to drive the car.

 

In that thread, clawson wrote:
In our work all source is heavily commented with Doxygen for the "nuts and bolts" but for every module we also have separate doc\modname.md in MarkDown that also feeds into the Doxygen process and produces "system diagrams" and more verbose documentation about where the "black box" fits into the overall picture.

 

https://www.avrfreaks.net/commen...

it's that second, highlighted bit that's so often missing.

 

frown 

 

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Surely the quality of the documentation is down to the author? Sure a uart.h may only cover the API of the UART but nothing stops you sprinkling MDs all over the tree to document it at all levels (our internal coding standard mandates this).
.
Take a look at github for example. That encourages use of a readme.md at the highest level which can link to MDs in lower layers so everything is covered from the highest level to the nitty-grittyest detail.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

 but nothing to tell you how to drive the car.

Yep--I used some graphics packages several years ago....hundreds of pages of documentation of internal structures, etc, with great detail of seemingly hundred of different commands.  But absolutely no hint of how to do anything.  No mention of which commands are commonly used, or which ones are used together, or so much as to how to draw anything (or configure to draw anything).   As if someone threw a handful of electronic components at you and said, here's a TV, enjoy it!

When in the dark remember-the future looks brighter than ever.   I look forward to being able to predict the future!

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

This is very very common; not just with libraries but with complete stand-alone software packages: they answer all the questions you *don't know to ask* but rarely assume you're a neophyte. So often, you need to know how to use a package or a library before you can ask the question 'what does it do' let alone 'how does it do it' or even 'how do I...?'

 

Neil

 

(Not looking at xmllib, oh no...)

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

clawson wrote:
Surely the quality of the documentation is down to the author?

Absolutely.

 

nothing stops you sprinkling MDs all over the tree to document it at all levels (our internal coding standard mandates this).

Indeed - so why do so few actually do it?

 

barnacle wrote:
they answer all the questions you *don't know to ask* but rarely assume you're a neophyte. So often, you need to know how to use a package or a library before you can ask the question 'what does it do' let alone 'how does it do it' or even 'how do I...?'

Exactly.

 

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
Last Edited: Tue. Mar 23, 2021 - 09:04 AM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

awneil wrote:
Indeed - so why do so few actually do it?
If you have ever worked to deadlines you know the usual pattern: author first, document later. As you are still trying to make the software work 3 months after the launch deadline there's never any time to stop and document it.

 

As in the organization where I work there needs to be procedures and coding standards where things like the requirements, design, documentation, test phases are steps as important as the actual software authoring. But left to their own devices programmers just do "the good bit" first and ignore the other essential steps.

 

(I have seen instances of things like requirements or UML being done after the software though - so I guess somethings can never be quite perfect!)

 

PS I think some automated tools can help - the kind of things that ensures that every class member has a comment saying what it is (well some text in a Doxygen comment anyway!) can help - have Jenkins/Github bounce the build if these are not found.

Last Edited: Tue. Mar 23, 2021 - 09:13 AM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

With open-source stuff, I think there's also the issue that contributors are mostly interested in writing code - not providing documentation.

 

I guess there's also the demotivating factor that so few people actually bother to read documentation?

 

frown

 

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

awneil wrote:
that contributors are mostly interested in writing code - not providing documentation.
I guess if they are giving us stuff for free you are can't really complain about the quality ;-)

 

But there are some good examples of fairly well documented stuff like Fleury, LUFA, FatFs etc.

 

(curious how the ones people choose to use regularly happen to be the ones that are well documented - funny that!)

 

One thing that can go a million miles towards revealing the author's intention for their magnum opus is simply a ./examples/ folder in the project !

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

The biggest problem with open source is not really the documentation of functionality, but the need of HW setup  and what kind of resources that are needed (max time of other ISR's or even "size" of atomic block etc.).

So try to get more than one open source packet to work at the same time can often be a challenge.