MS2 new documentation discussion

[jsmcortina]

If you haven't already, please read the new draft PDF manuals available from the Downloads page.

I could really use some detailed feedback.
"They look ok" is nice to hear, but doesn't offer me much guidance. I need to hear things like "I tested the TFI wiring and settings and it works ok" or not.

I'm presently wrestling with starting the setting up / tuning manual. But here lies a problem... between the different MS2 products there are enough detail differences that the manuals could get very cluttered.
e.g. my original plan was to have a hardware manual for each product (Microsquirt, Megasquirt-2/V3.0 etc.) that seems ok.

I've just drafted out the fuel hardware section (pumps, plumbing etc) and put that into the setting up manual, but wouldn't it make more sense to be duplicated in each of the hardware manuals?

Next thought was the tach in / ignition setup. That by its nature contains a lot of hardware and the capture edge settings are likely different between each product. I had originally hoped to write one common section, but there will be so many references to the differences, should that also be duplicated and tailored to the hardware ?

My guiding principle is a manual that works for the customer - even if it makes it harder for me to maintain.
I'm thinking that if we keep the manuals "clean" with few multiple choice questions, it will work better and be easier to follow. (e.g. the MS3-Pro manual is straightforward as it covers a single piece of hardware with no user customisation, there's no clutter talking about MS3 vs. MS3X or V3.0 vs. V357 etc.)

Thoughts ?

James

[juansh2385]

I the diagnostic logger could use more pictures that shows how a specific problem will be seen in the logs. I mean a picture of a log that has wrong polarity/triggering in the wrong ede etc.

I think that for the different ignition mode what can be done in the manual give a name for a custom mode like a glossary/dictionary that explain how to do the mode then in the part of the manual that you explain the necessary mods for that application you just write the name for the mod and the user can look what mod you are talking about.

Example

Setting for 420a
you need xxx mod for tach input and this is going to trigger in the falling edge this xxx for direct ignition output etc.

I think that this can help avoid the cluster of information and in a ways standardize the way of doing things with a proven setup

[pigga]

Hi.
Referring Tooth logger it could be helpful to add some examples from http://www.msextra.com/doc/general/toot ... mples.html

To my eyes the EAE manual could need some improvements. Because the EAE stuff is not bad at all. So it's worth to encourage more people to use it. I think the key point is that at EAE it is not quite obvious which value causes which behavior of the algorithm.
So maybe it would be good to add something like

"This will happen if you change the referring EAE values:

ADW Coefficient:
Large values = Much correction, big amplitude of EAE gauge at engine load change (60-140%)
Small values = Less correction, small amplitude of EAE gauge at engine load change (90-110%)

SOW Coefficient:
Large values= Less correction at engine load change (90-110%)
Gauge goes quick back to "Zero position" (i.e. 100%)

Small values = Much correction at engine load change (60-140%)
Gauge goes back to "Zero position" (100%) very slowly..."

[JoseMiguel]

I the diagnostic logger could use more pictures that shows how a specific problem will be seen in the logs. I mean a picture of a log that has wrong polarity/triggering in the wrong ede etc.

I think that for the different ignition mode what can be done in the manual give a name for a custom mode like a glossary/dictionary that explain how to do the mode then in the part of the manual that you explain the necessary mods for that application you just write the name for the mod and the user can look what mod you are talking about.

Example

Setting for 420a
you need xxx mod for tach input and this is going to trigger in the falling edge this xxx for direct ignition output etc.

I think that this can help avoid the cluster of information and in a ways standardize the way of doing things with a proven setup

2nd to this!

I would like to see this options completely specific for the triggers that require them. For example, the neon trigger works in one way and only one way (trigger angle and capture edge). This should be specified for this triggers.

Manual looks so much professional now!

[jsmcortina]

I would like to see this options completely specific for the triggers that require them. For example, the neon trigger works in one way and only one way (trigger angle and capture edge). This should be specified for this triggers.

Agreed, that's what I want to do. I will most certainly need some help achieving this.

Manual looks so much professional now!

Thanks.

James

[jsmcortina]

No other comments?

James

[cygnus x-1]

No other comments?

James

I did download and sort of peruse through the manuals. They're HUGE so I think it will take awhile for people to get through them.

From what I can see they are definitely an improvement though. Just having everything in a single searchable document is a good start.

Will there be a (non-Microsquirt) MS2 hardware manual as well?

EDIT: Just read the first post again. Yeah, I think having a hardware manual for each major hardware version (Microsquirt, MS2V3, etc.) is a good idea. It would also be good to detail as many of the specific ignition options as possible. It is a huge task but I think it will be worth it in the end.

C|

[lagos]

Have you ever thought about doing a wiki style manual? Something that can be created by a central source but also community updated.
This has worked very well for Arch Linux, and their wiki is pretty much considered the gold standard to being up to date and very detailed. I think this kind of thing could work for the MS community as well.

https://wiki.archlinux.org/index.php/Main_page

[lagos]

Under the EGO correction section, the PID controls need to be explained in more detail, along with other things like controller step size, etc.. they should elaborate on the info that you can find in the tool tip.

It would also be cool if I could click on the tool tip directly to take me to a specific page in the pdf where I can read more info.

[Nfsjunkie91]

Under the EGO correction section, the PID controls need to be explained in more detail, along with other things like controller step size, etc.. they should elaborate on the info that you can find in the tool tip.

It would also be cool if I could click on the tool tip directly to take me to a specific page in the pdf where I can read more info.

I agree with you regarding PID tool tips, I ended up getting online and researching PID control. I really agree with what you say about a wiki though, like 100%! The user community could provide a lot of information on features that are currently minimally documented. I think the biggest advantage would be the ability to add content such as embedded videos demonstrating how certain settings can affect a motor, video of how to correct problems, etc. Wikis are wonderful things, and would go well with the open-source nature of this project.

I can see updates being a concern, but as the devs are looking to finalize MS2E (according to the roadmap) this shouldn't be a big issue.

[jsmcortina]

I have no plans to implement wiki style documentation.

James

[Matt Cramer]

An unofficial wiki might have its place. But the reason I ended up choosing MegaSquirt over a competing system when I first got started was that the competition was using a wiki for their primary, official documentation, and the people who had edited it seemed more concerned with either documenting how much they hated MegaSquirt than documenting how to use their system. There may be some wikis out there that can be a gold standard for documentation, but keeping one from turning into a lead standard (obviously filled with junk), or worse, an iron pyrite standard (looks like gold to someone who isn't familiar with the material, but on closer inspection isn't nearly as good).

[suberimakuri]

Great job. Searchable in one document and plenty of detail

[JoseMiguel]

An unofficial wiki might have its place. But the reason I ended up choosing MegaSquirt over a competing system when I first got started was that the competition was using a wiki for their primary, official documentation, and the people who had edited it seemed more concerned with either documenting how much they hated MegaSquirt than documenting how to use their system. There may be some wikis out there that can be a gold standard for documentation, but keeping one from turning into a lead standard (obviously filled with junk), or worse, an iron pyrite standard (looks like gold to someone who isn't familiar with the material, but on closer inspection isn't nearly as good).

James

I know that the purpose of a wiki is to permit edition from a broad amount of public. This can be both powerful but can lead to unexpected/unwanted content.

Is it possible to have a somewhat "restricted" wiki in which only people with X posts can edit? many of us are willing to help and a wiki content manager will automatically solve indexes/searches

[Matt Cramer]

One thing I noticed in the MicroSquirt hardware manual: the PWM to stepper box doesn't appear to be available, and a few threads have noted this.

[Matt Cramer]

Looks like Manu found a couple tool tips in MS2 that accidentally refer to MS3-only features:

http://www.msextra.com/forums/viewtopic ... 01&t=54097

[jsmcortina]

One thing I noticed in the MicroSquirt hardware manual: the PWM to stepper box doesn't appear to be available, and a few threads have noted this.

Here you go:
http://www.efisource.com/shop/microsqui ... r-adapter/

James

[Manu]

Hi James,

Is there a documentation page dealing with all variables available in code (MS2 & MS3)? If not, a such page should be useful for users so they can know what they can do with programmables outputs, logs, etc...

Same thoughts can apply to status code (engine status, etc...)

Regards,
Manu

[Trev16v]

Making the manuals available in HTML format could allow mobile applications like MSDroid to use them more effectively. There would be some interesting possibilities.

[jsmcortina]

Hmm... I'm moving away from HTML as the web-centric docs are often difficult to print and not so easy to distribute to customers.

James