Effective documentation updates

Part of Gen7 electronics' success is its extensive documentation. Tables with links to several vendors of every single part, assembly instructions with a picture for every single step of assembly, detailed instructions on how to get life into what was assembled before, troubleshooting guides, and so on.

A bit of a problem is, even small changes require a ton of documentation changes. For example, making Gen7 fit for 24 volts requires replacing two resistors. Design change, manufacturing and testing would take a day, updating documentation would take something like a week. Because the color stripes on these resistors change, almost all assembly instruction pictures have to be remade and replaced, an electronics has to be built just for getting the pictures and so on. Also the wiki page has to be copied to a new one, reviewed in every single sentence, templates updated, etc. etc..

Seven times more time on documenting something new than doing the actual development is not exactly an ideal relationship.

So I'm looking for more effective documentation methods or ways to reduce documentation amount or documentation changes while keeping the ease of assembling the electronics. This could accelerate development a lot. Any ideas? Comments?

---

Generation 7 Electronics	Teacup Firmware	RepRap DIY

Git

Quote

Git

Could you elaborate, please? Git is a versioning tool and the wiki does versioning, too. So I don't see the advantage and also not how this would make the pictures or text reviews.

Pages are copied instead of updated because instructions for older versions have to remain visible. For example, there are still people building a v1.3.1 today, a version about a year old. At least I think they should remain visible.

---

Generation 7 Electronics	Teacup Firmware	RepRap DIY

Well it can't fix your pictures, but it sure can help to make changes to large amounts of documentation easily.

Just throwing ideas out there.

Pictures are a huge benefit in your documentation, but for this point also are a huge disadvantage.

I'm now taking a look to gEDA, and it's an amazing program. Maybe it's a long term achievement, but would be interesting to implement an export utility for soldering steps, like the realistic photo-mode export on PCB, but taking some parameters like soldered components, connectors, and so on, using standard footprints or self-generated images. Yeah, a very big work, I know

WIKIs are wikis, git is a repository house. Far better for true project documentation storage imo. Wikis are, ime/imo too subject to external intrusion.

And there is no reason that one cannot contain and provide linkage to older versions in what is, after all, defined as a standard version control system...doh.

Yep if he has pictures for every version, git will keep track of that too. I really think it's a perfect solution and not just for software.

He could even go a step further and use Github. Seeing as how I'm sure his sources are GPL it would be free to him.

Edited 1 time(s). Last edit at 01/29/2013 05:01PM by xclusive585.