Anyone Can Write / Code

On Techwr-L, there was a thread that originated with Lin Sims asking about how to maintain large documents in MS Word. The current documentation is maintained within FrameMaker, a tool traditionally known for being able to "handle" large documents. Notes:

• There's been a lot said and batted around since this post earlier this week 
• I've never run into the implied mentality that "anyone can write the documentation" throughout my career, though I've read plenty of horror stories about it!
• I have no idea how to read the code example Peter Neilson cited in his response. I can only assume that putting in the comments where he did would yield different results than the original code. It makes me really wish I knew how to read C++ source code as I wish again I had 26 hours in the day:
• 1 extra hour to devote to learning how to program
• 1 extra hour for practicing drums!

---

1. On Mon, 24 Nov 2014 23:56:22 -0500, Dan Goldstein wrote:
   > 100 pages? Heh. Tech writers have testified to Word documents that
   > they maintained with 300, 600, over a thousand pages, complete with
   > graphics and tables.
   >
   > Of course, this requires a lot of training. Jonathan West wrote, "You
   > have to put as much effort into learning it as you would have to in
   > order to learn Frame."
   
2. To which Peter Neilson wrote:
   If I'm not mistaken, the particular reason for the shift from Frame to Word is so that the SMEs can modify the documentation source directly, presumably saving some effort.
   
   Perhaps the SMEs would not mind if tech writers were permitted to make changes directly to their C++ source code? Just adding comments, nothing more.
   
   Not only does everyone know how to use Word, but everyone knows that /* and */ delimit comments in C++, and that // indicates comments on a single line.
   
   What could possibly go wrong?
   
   Here's an example. We take this code:
   
   // Our Fine Example
   #include
   using namespace std;
   int main()
   {
   int a = 3, b = 5; /* Use last values set */
   a = 4, b = 13;
   a = 2, b = 35;
   cout << a << " + " << b << " = " << (a+b) << endl; return 0; } and we'll just add two comments... // Our Fine Example #include
   using namespace std;
   int main()
   {
   int a = 3, b = 5; /* Use last values set */
   a = 4, b = 13; /* Do we use these? /*
   a = 2, b = 35; /* No, it's these, right? */
   cout << a << " + " << b << " = " << (a+b) << endl;
   return 0;
   }
   
   It still compiles without error and runs.
   
   Have we hurt anything?