User Tools

Site Tools


getting_started_for_authors

Let's say you are a new author and you've agreed to write one of the clauses. This is my suggestion for how you go about it.

First, you need an SVN enlistment on your machine with a suitable SVN client. I'm assuming you've got this far. This means you are able to lock files, edit them, and commit your changes.

You'll be starting from one of the clause templates that are already checked in. You will also have read the readme at https://dev.enterprisecomponent.com/repository/repos/UML-Spec-Simplification/trunk/Models/Metamodel/Specification/ReadMe.html.

Here are the steps I suggest you take.

1. Set out the basic skeleton of your chapter. I.e. create all of the subclauses, according to the organization that you will find at https://dev.enterprisecomponent.com/repository/repos/UML-Spec-Simplification/trunk/Documents/UML-Specification-Organization.doc. In each subclause, insert a link to the appropriate abstract syntax png, which you should find already there in your folder. Give it a caption (just the name of the subclause) and set the style of the caption to omg-figure-caption. Make sure the figure numbering works properly: chapter-number.figure-number (period separator, not hyphen). You can set these things in the Insert Caption dialog. At the end of this step you should have the basic skeleton of your clause and subclauses, with each subclause named, and all of the abstract syntax figures linked to and correctly captioned. You can check this in with a checkin comment “Chapter X skeleton”. In every case you are saving as html (NOT filtered html). Word should do this automatically.

2. Acquire all of the relevant content for your chapter, without trying to do any editing. For each metaclass that you are writing up in your subclause, do a search (with “match case”) in UML 2.4 Superstructure from Adobe Reader. Find all of the descriptive and semantics paragraphs that relate to your metaclass and copy and paste them, one at a time. If you set your target paragraph style to omg-body and paste with “merge formatting”, you get a decent result. You can set your paste defaults in Word to merge formatting when pasting between documents. You have to copy one-at-a-time because the paste will lose your paragraph markers. If the source text is bulleted or indented, use the Word bullet or indenting to make it look right.

Remember that each metaclass may be described in several different places. Just go and get them all. Get the semantics, notation, and examples, and put them into the right sections. When you've finished one metaclass, take a breather and move onto the next.

Get the figures as you go. Whenever you encounter a figure, use Adobe's snapshot tool to copy it. Paste it into Paint, first setting Paint's image area to tiny. Save it as a png file, with a name like ExamplesBlahBlahBlah.png. BlahBlahBlah is a unique descriptive phrase derived from the figure's original caption. Link it into your doc in the right place. Resize it if needed. Give it a caption - you can copy the text of the caption from the original doc. Make sure the format of the caption is omg-figure-caption. I found it useful to keep Word's “apply styles” dialog open all the time, so you can make sure everything has an omg-* style or h1 .. h4 style.

When you've done your whole clause (it make take a couple of days for a big one) commit it to SVN with a comment like “First complete draft of PQR. All relevant material included, with no editing.”

3. Systematically go through your chapter and change the spellings of all metaclass names so they are capitalized and PascalCased - TemplateParameter rather than template parameter. Use search and replace.

4. Commit that to SVN again.

5. Now it is time to start rewriting. What I do myself is print it out and read it through, marking it up with a pencil. Rewrite to remove repetition and redundancy, use proper terminology and fix the grammar. When you encounter something that is wrong or contentious or needs further work, use Word commenting to make a note of it. When you have finished this, commit it to SVN, with a comment “ready for review”.

getting_started_for_authors.txt · Last modified: 2011/02/22 11:55 by admin