Documentation: dow does this reference manual for a hardware module look? - Page 1
Forum section: electronics / projects

author: technix
author_rank: Super Contributor
timestamp: September 23, 2015, 07:10:09 pm
content: I am going to sell this so I need to make sure my documentation look good. Links won't work yet, though, as I have not finished all the software.

author: tszaboo
author_rank: Super Contributor
timestamp: September 23, 2015, 07:13:18 pm
content: Pictures, diagrams are missing.

author: technix
author_rank: Super Contributor
timestamp: September 23, 2015, 07:59:15 pm
content: Quote from: NANDBlog on September 23, 2015, 07:13:18 pmThose are elsewhere. There are several manuals for this product:M177v2 Service Manual (corresponds to the PCB)M177v2 Reference Manual (corresponds to the firmware)M177v2 User Manual (basic usage)librhid Reference Manual (corresponds to the software running on Raspberry Pi)

author: Mangozac
author_rank: Frequent Contributor
timestamp: September 23, 2015, 09:43:15 pm
content: I like the styling and layout - professional but "friendly". What is the main font you've used?

author: dom0
author_rank: Super Contributor
timestamp: September 23, 2015, 11:42:55 pm
content: Re. layout, you really want more white space between header, footer and content.

author: technix
author_rank: Super Contributor
timestamp: September 24, 2015, 02:54:23 am
content: Quote from: Mangozac on September 23, 2015, 09:43:15 pmSan Francisco Text in various weights. This is the new default user interface font of Apple's OS X El Capitan and iOS 9. The monospace font os Source Code Pro.

author: MisterDiodes
author_rank: Frequent Contributor
timestamp: September 25, 2015, 01:14:59 am
content: Just as Devil's Advocate here: I read the overview, but I still don't know what it does. Can you clearly explain what it's for in one sentence?Otherwise with a little more spacing it looks good.

author: T3sl4co1l
author_rank: Super Contributor
timestamp: September 25, 2015, 01:29:42 am
content: Guessing it's done in Word?Word's defaults are always the ugliest, so good on you: you're using your own theme of font, colors, styles.First impressions:Cover page: seems simple and straightforward. Could maybe have a date or "build" or something like that, but maybe that's encoded in the "1C112" version number, so that's fine. I like to use a "current date", which identifies the document version at the moment of printing, in essence.Second page: good, table of contents. Seems specific. Distance to the header is rather tight.4th page: Yeah, heading is definitely tight. It should be a smaller or lighter font/style, and much more than one parskip away from the body. Two or three would do it. (Besides smaller font or different color, using all caps, or italic/emphasis, is also a common setting for headings.)I'm not sure how important it is to note the MCU inside -- if this is an OSHW or "you can screw with it if you like" kind of device, that's very nice to note. If it's more intended as a black box you wire up and use as a display "shield", it might not be very important or necessary. (Accordingly, signals, timing, etc. should be listed, in the abstract, without relation to some fixed platform. If I want to drive it from discrete logic, I should be able to, y'know?)That said, since it's intended specifically for RPi, and physically mates with it (although, a drawing is not provided!), probably not a big deal either.I'd like to see specs, like, whatever electrical signals are provided or accessible (logic levels, timing); power supply requirements and draw; temperature limits; the usual tabulated stuff. Graphs probably not important here.By the way, this is probably the best document I've ever seen come out of China (or the general area). Do more of this!Tim

author: ez24
author_rank: Super Contributor
timestamp: September 25, 2015, 02:56:07 am
content: Quote from: MisterDiodes on September 25, 2015, 01:14:59 amWhew I thought it was just me

author: ez24
author_rank: Super Contributor
timestamp: September 25, 2015, 03:12:58 am
content: What ever this is, it is not for the faint of heart:QuoteAnd I thought this had something to do with a LCD12-core Xeon ! (I have to check if I have one somewhere)

author: marshallh
author_rank: Unknown
timestamp: September 25, 2015, 03:29:29 am
content: Make use of whitespace as a visual cueIt allows your brain to "separate" blocks of information to avoid the dreaded wall-of-text problem.Also you can use blocked grayscale elements.Also, it's just my preference, but I prefer serif fonts for anything that is usually printed. It's easy to lose track of how sizes when you're looking at it scaled up on your monitor -- print it out and try reading it dead tree form.

author: eas
author_rank: Frequent Contributor
timestamp: September 25, 2015, 03:47:46 am
content: Quote from: dom0 on September 23, 2015, 11:42:55 pmThe line spacing feels cramped too.

author: technix
author_rank: Super Contributor
timestamp: September 25, 2015, 03:00:26 pm
content: Quote from: T3sl4co1l on September 25, 2015, 01:29:42 amAlmost the same thing as Word, I used Apple Pages (part of iWork, free with any new purchase of a Mac now, I had to buy it in a box back then and yes design boards, write code, program microcontrollers and document them using a Mac running OS X) I have to restrict myself to grayscale since that is all my printer can do (and I prefer documentation in dead tree form more than digital)I am going to try change the distance between heading and contents if the software allows me to do so. And yes this is OSHW so you can f*** with it anyway you like, and most of the pins are broken out one way or another anyway.

author: technix
author_rank: Super Contributor
timestamp: September 25, 2015, 03:46:09 pm
content: Updated it. More comments?

author: Neganur
author_rank: Unknown
timestamp: September 25, 2015, 05:15:41 pm
content: I feel like wanting to place an article in front of the sentences starting with 'M177V2...' In section 1. Overview.You can do without it if it's a company name (e.g. "Apple is a multi-billion company...") etc but you are defining an instrument and refer to it by its model number.I think it also reads better if you write "The M177v2 is a ..."That's my 2 minute impression.