Kim, Michael, Francis, John, et al.: I should say something about myself first of all so you'll have a better understanding of what I hope to contribute.
I have always been good at working methodically and seeing patterns. I read carefully and notice things that seem not quite right. (A psychologist would score me high on anal retentiveness---but I think everyone who gravitates into editing has these characteristics.) With regard to the EMC2 documentation, I see: 1) content --- I may notice incorrect word usage or missing text, but I do not believe I will make much of a contribution at this level. This is especially true for the foreign (to me!) language versions. A long long time ago I was competent in technical German but not any more and never in the context of industrial engineering. I might be able to manage ordering a beer in French or Spanish if I were thirsty enough! Michael brings up a huge issue when he asks how we keep the content of the various language versions in synch. I could envision a content management system (CMS) that properly supports this function but I don't think raw git is it. Perhaps someone out there in the world of open software has conjured up a decent system based on git. I'll look. I think it's too big a reach at the moment to create one on our own with the human resources available, but, hey, I've been wrong before and I could be wrong now. It didn't take Andreas long to create git itself. In the meantime, perhaps Michael, Francis, and others who understand the issues could propose a way for agreeing when the French, German, and Spanish versions are acceptable for release? I see no purpose being served by publishing them side by side "as if" they were ready for prime time when they are not. Better to seem rude and publish only the English version. By the way, Kim, many of the "Error: no ID for constraint linkend.../XREF to nonexistent ID..." messages I looked at result, not from the splitting of source, which is certainly one possibility, but from partial language translations, for example, a tag in another language referenced by a link in English. I see no point in trying to fix these piecemeal until the translations are more complete. 2) markup --- Here I can contribute. Mistakes like the "images::" versus "image::" tags which resulted in missing figures are my bread and butter (think of me as a human lint program). And, yes, John, I try to use all the tricks of the Unix/Linux trade to my advantage---capturing stdout and stderr streams, for example; grep'ping and find'ing patterns and anti-patterns in the sources and the output; creating and comparing file lists, word lists, markup lists, etc. This is the kind of work that motivated the Bell Labs guys to invent Unix. 3) work flow --- the tools like asciidoc, make, etc., and the use of them to create pdf and html documentation out of 1) and 2). Here I'm behind you all but I think I'm catching up. Again, I think I can contribute. As a trivial example, several image files do not appear in the html documentation because they are available only in .eps format. The tool chain should catch this automagically. I know how thankless a job editing major collective technical works can be (I could recite previous examples of not being thanked, but that would just prove I also have masochistic tendencies!). Still, EMC2 seems worth the effort to me, and I infer it does to you too. Final comment: I'm not interested in being a critic or a blamer; I'm only interested in getting a good result. I can be blunt and sometimes my remarks may be unfortunately worded, but I never intend them to be an ad hominem attack. "The facts, Ma'am, just the facts" was the tag line for a fifty year-old US detective show but it works here too. Regards, Kent ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save $700 by Nov 18 Register now http://p.sf.net/sfu/rsa-sfdev2dev1 _______________________________________________ Emc-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-developers
