Hey all - just wondering how you all document your projects.
I choose to write a little manual, instead of just using Fritzing or README files. See the attached as an example (that project is a very simple one, which mainly serviced as a test bed for my new 3-D printer 
)
Any suggestions welcome. Is this a sub-optimal way to document, outside the standard; or am I ok doing it this way? It is certainly clearer for me.
envirometer-manual.pdf (1.2 MB)
Looks great.
I too use PDFs for documentation.
I make the PDFs in MS Word.
Suggest a few more comments in your sketch.
Flow charts are sometimes useful.
I make them in Pages on the Mac. Same principle.
OK, more comments in the sketch - will do! I guess these are a little sparse?
That's beautiful @michaelwillems. This is such an important part of any project, which is so often skipped or neglected.
It's important to document the source of the libraries you are using in an Arduino sketch. As more Arduino libraries are created every day (a survey I did indicates there are over 10000 unique Arduino libraries), it becomes increasingly likely that multiple Arduino libraries will contain any given header file name. So it can be very frustrating to try to track down a library dependency based solely on the header file name in the #include directive, which is most often the only information we have about a dependency.
So I would recommend adding a comment specifying where the library can be found. You also might specify the version of the library the sketch was written for, since future changes to the library's API might make the library no longer compatible with your sketch.
My other concerns are around the use of a PDF:
Something somewhat annoying about copying code from a PDF is that all the leading whitespace, and thus the indentation, is lost. Sure, I can just do an autoformat after copying, but many won't do that. Also, often I am getting code from PDFs shared by people who are having trouble with their sketch. In this case, the user's indentation can sometimes show their intended code structure, which is not always how the code is really structured. For example:
if(something)
doSomething();
doSomethingElse();
Version control is very important for any complex project. Even though version control is most predominant in software, I think it's also important for technical documentation (which is often hosted in the same repository as the code anyway). Due to their binary nature, version control of PDF files is not very good. You're not going to be able to easily see a diff of the exact changes to the content from one commit to the next.
In the case of projects where you welcome collaboration from the community, the use of PDFs also makes the documentation unfriendly to contributors.
The solution to these last two issues is to generate the PDF from a standard markup format. The most popular of which is Markdown. Coming in a distant second would likely be AsciiDoc. There are excellent tools for converting source in either of these languages to PDF (e.g., pandoc and asciidoctor). The source content will lend itself well both to version control and collaboration.
Excellent feedback, thanks.
Yes, the libraries are a problem - half the time even I do not know which one gets used because I have somehow ended up with several. Groan. There must be a better way to manage that...
Code: yes. I wonder if I should document not here but also have a link to a download location for the actual sketch somewhere (if so, where)?
Format: perhaps a PDF but also available in an editable format, perhaps also from the same download location? That way there is at least a way to see how I wrote the documentation before anyone altered it. EDIT: I think that is what you are suggesting... do these tools give me the fine layout control that Pages does?
Version control: also a very good point, that is not clear right now.
I don’t use the above site but many do.
I add a line or 2 at the top of sketches where the library came from.
Example:
//Use I2C library: GitHub - duinoWitchery/hd44780: Extensible hd44780 LCD library
//LCD Reference: LiquidCrystal - Arduino Reference
One more question... newbie here, sorry if this is dumb, but: how do I in fact see the source of the libraries I use?
When I check my Arduino libraries folder, I can't see where I got the library from. Even when I look into the library's files (readme, *.h, etc) I still can't always see where the library originated or what version it is.
I must be missing something simple?
I just Google it.
example:
Google DS3231.h github
One of the results:
Always best to compare it to the version in your libraries folder.
Libraries that come with the IDE I don’t worry about.
Mmm. But of there's 3 libraries around the world with the same name. is there any way for me to see which one I am using? (This is a newbie question, sorry)
Always best to compare it to the version in your libraries folder .
Not sure where Apple saves those libraries that you download from within the IDE 
.
I know where they live, but there's the rub: in those library folders, where do I see the source and the version number? Some indicate it in the .h or in the readme file etc, but it appears that some don't, or at least not clearly so I understand it.
Look for the .h and .cpp files.
I agree you have made an excellent document, way more than anyone would need to duplicate or use as a point of departure.
I did not miss any drawings of the enclosure and other mechanical aspects of you project.
I only have one thought: the schematic could be improved. In particular the area that has a swastika-like tangle of crossing wires. Also and wires that are not horizontal or vertical should be made so.
Your drawing program for the schematic should help you do this, or make it easy to do.
But really, nice work!
a7
Larry,
And sometimes they are clear, but sometimes they say stuff like this - rather than "where" and "version", they give me stuff like...:
/*
DS3231.cpp: DS3231 Real-Time Clock library
Eric Ayars
4/1/11
Spliced in DateTime all-at-once reading (to avoid rollover) and unix time
from Jean-Claude Wippler and Limor Fried
Andy Wickert
5/15/11
Fixed problem with SD processors(no function call) by replacing all occurences of the term PM, which
is defined as a macro on SAMD controllers by PM_time.
Simon Gassner
11/28/2017
Fixed setting 12-hour clock in setHour function so that 12:xx AM is not stored as 00:xx and corrected
the setting of the PM flag for 12:xx PM. These address certain DS3231 errors in properly setting the
AM/PM (bit 5) flag in the 02h register when passing from AM to PM and PM to AM.
David Merrifield
04/14/2020
Released into the public domain.
*/
Yeah, that tangle bothers me. But how else do I cross four wires?
OK, I will be more careful next time to avoid diagonals. Good point.
If you turn on "Show verbose output during: compilation" in File > Preferences, the Arduino IDE does show the location of the library that was used in the black console pane at the bottom of the Arduino IDE window after you compile the sketch.
This points out one of the great benefits of documentation in my opinion. We tend to think of documentation as being for other people. Sometimes that can make it seem not worth the effort for a casual project which might not end up having many users. But over and over again I find that I am the beneficiary of that effort when I return to a project after some months or years and have forgotten all the details.
It's not super great at the moment.
There is a feature in the Arduino IDE where you can add a special URI in the comment that opens a Library Manager search:
https://arduino.github.io/arduino-cli/latest/sketch-specification/#libraryboards-manager-links
but the search might end up having multiple results depending on the keywords used. And there also isn't a way to specify a library version via the URI.
It is possible to bundle the libraries with the sketch, so that it's somewhat of a self-contained package. Some dump the library files directly in the sketch root folder, but that can become messy. A cleaner, though somewhat more complex approach is to put the libraries under the src subfolder of the sketch:
https://arduino.github.io/arduino-cli/latest/sketch-specification/#src-subfolder
where they can stay packaged in their standard folders rather than being all jumbled together in a single folder.
There is work in progress currently to improve on this situation. The initial planning is now done and we are requesting input from the community before the development work starts:
I'll second LarryD's recommendation of GitHub. Probably 99.9% of all code in the Arduino ecosystem is hosted on GitHub. Use of GitHub is going to make a project most friendly to collaboration because that is where essentially all the potential contributors are.
That's correct. The source content is written in Markdown or whatever. All editing is done on that source content. The PDF file is the rendered output of that source content.
I have never used Pages, and haven't gotten very deep into the capabilities of pandoc and Asciidoctor. I have primarily worked with Asciidoctor simply because Arduino had specified that AsciiDoc should be the markup language of the source content for those projects.
The more recent documentation projects I've been working on have instead generated static websites from Markdown source content. The generation is done using MkDocs and then hosted on GitHub Pages. You can see an example here:
https://arduino.github.io/arduino-cli/
It comes back again to the value of documentation, this time on the part of the library developers.
Modern Arduino libraries have a metadata file named library.properties. You can open it in a text editor. In this file, there is a url field that often (but not always) contains the URL of the library's source. That's as close to a standardized way of providing this information as it gets. That metadata file also contains a version field that will tell you which version of the library is in use.
This metadata file was introduced in Arduino IDE 1.5.x. Before that, there was no such thing. Backwards compatibility was retained for the old style library without metadata and so you will still find libraries without metadata. But it is required of all libraries added to the Arduino Library Manager index, so most library developers have added one by now.
In some cases, the location of the library on your computer can provide a clue to where the library's source is. The ones in the libraries source folder of your sketchbook folder could be installed from Library Manager. In this case, each library must have a unique name and the folder it is installed to is named after the library name.
The ones in the libraries subfolder of the Arduino IDE installation folder come pre-installed with the Arduino IDE installation. These are all also in Library Manager, or you can find them here:
https://github.com/arduino-libraries
The ones that are bundled with the boards platforms are hosted in the repository for that specific boards platform. For example, here are the platform bundled libraries for the Arduino AVR Boards platform:
https://github.com/arduino/ArduinoCore-avr/tree/master/libraries
Note that each boards platform can have a library of the same name, but configured specifically for the architecture of that board. So the Wire library of the Arduino AVR Boards platform is not the same as the SPI library of the Arduino SAMD Boards platform. But this is not apparent to the user because they have compatible standardized APIs. The user will already have these libraries installed, so it's not necessary to document their specific source, but it's good to explain that they are pre-installed so the user doesn't go hunting around for the library unnecessarily.
This is the pain every user of a sketch found on the Internet without documentation of the dependencies has suffered. Those of us who help people on the forum go through it more often than most.
If the schematic starts getting cluttered, use Net Names on those pins that are connected together.
Of course the coloured lines are not seen 
.
Thanks for that excellent detailed response - useful for many I am sure.
I think I am unlucky with the libraries in this particular case, because they don't indicate clearly, even in the files you mention (I did check them all with a text editor). Delighted that you are working on improving this, and I will happily look at that. Tomorrow after work, because it is midnight again. Funny how that creeps up on you when you're having fun!
Grrrr, you advocate a "search a word" schematic.
[soapbox]
If a Net Name has more than two connections, how does a Net Name tell you there is more than two ends to its net?
Proper layout and time spent on diagram and documentation, may take as long as the project development but a PROPER circuit diagram for signal tracing and trouble shooting is very valuable.
Net Name, OK for a PCB design, a computer does the reading, but when it come to us poor humans, the format is different.
A proper wire connected schematic is always going to be better than a "search a word".
With computer circuits, one schematic for data and address bus, another for signal and power supply.
[/soapbox]
The destructible site has a basic template to make you present your project in an ordered and tidy fashion. One of the very few good things about it, if it is used properly.
Tom... 
I can clear up a couple of them at least:
#include <LiquidCrystal.h> // for LCD display
I'd be willing to bet this is the official library of that name which is bundled with the classic Arduino IDE installation. The source is here if you want to do a comparison:
https://github.com/arduino-libraries/LiquidCrystal
But the user should install it via Library Manager. Even though this library comes pre-installed with the classic Arduino IDE. Users of Arduino CLI won't have it installed. Currently, it is also not bundled with Arduino IDE 2.x (though that might change in the future). So I think it is still worth specifying the source for this library.
#include <Wire.h> // for I2C comms
This is a platform bundled library. So the user will always have this pre-installed. As I mentioned in my previous reply, I still think it's good to add a note to this effect since the user may not realize this and so have a bad time trying to hunt down the library (which is not in Library Manager), and mess up their system by installing it like a normal library once they do manage to find and download some random version of the Wire library.
So that's the two easy ones at least.