Orchid XP v8 wrote:
> Yay! I suck. :-}

I'm assuming you're just being silly. I'm giving you an example of what an 
editor would do for you. It's criticism along the lines that "this is so 
well written it's worth my time helping you polish it so it doesn't have any 
of the tiny flaws that stick out like splinters on an impressively artistic 
wood carving."  If the paper wasn't already excellent, I wouldn't be 
bothering to point out where you spelled a word wrong.

When you're done, put it up somewhere and put the URL in your resume. This 
is the sort of stuff you should be putting in your resume. You do it very 
well, and as you say some of your actual paid work doesn't sound very 
impressive on a resume and you can't point a URL at the impressive paid work 
you do.

>> Add a concluding section, and explain in the abstract why someone 
>> might want to read the paper. These are two parts of any paper that 
>> are difficult to get right.
> 
> You're telling me...!

Let me give an example of an abstract and conclusion *I* would write for 
your paper, just to offer a perspective.

The abstract should say "this is what I'll talk about and why you should 
bother to buy/download/read the rest of the paper."  The conclusion should 
say "this is what I covered and I expected you to get, and if you didn't, 
you should read more carefully.

Again, take this as constructive suggestions from someone who spent years 
learning to write this sort of paper, submitting them to panels of editors, 
and getting rejected. ;-)

Abstract:
This paper describes a programming technique which is common in functional 
languages like Haskell but not widely used in imperative and object-oriented 
languages: the construction of combinator libraries. This powerful technique 
is introduced by way of the concrete example of a parser for text. Such 
parsers are common in all programming languages, so the contrast between the 
mechanisms used in functional paradigms with other paradigms will be easily 
recognized by programmers unused to functional concepts. Targeting readers 
for whom combinator libraries are a new concept, simple common syntax is 
used in the examples, leaving the introduction of Haskell's syntax to the 
end. No knowledge of Haskell or functional programming is required.


Conclusion:
This paper has introduced the reader to the concept from functional 
programming called a combinator, as well as given an example of how 
combinators can be collected into libraries to create sophisticated tools 
from a collection of simple operations. A combinator library for parsing 
strings is developed and explained. The result has a uniquely functional 
flavor that is unlike the solutions other paradigms would employ.




-- 
   Darren New, San Diego CA, USA (PST)
   Insanity is a small city on the western
   border of the State of Mind.

Post a reply to this message

>> Yay! I suck. :-}
> 
> I'm assuming you're just being silly.

Yeah, pretty much.

> I'm giving you an example of what 
> an editor would do for you. It's criticism along the lines that "this is 
> so well written it's worth my time helping you polish it so it doesn't 
> have any of the tiny flaws that stick out like splinters on an 
> impressively artistic wood carving."  If the paper wasn't already 
> excellent, I wouldn't be bothering to point out where you spelled a word 
> wrong.

Yeah, I got that part. ;-)

> When you're done, put it up somewhere and put the URL in your resume. 
> This is the sort of stuff you should be putting in your resume. You do 
> it very well, and as you say some of your actual paid work doesn't sound 
> very impressive on a resume and you can't point a URL at the impressive 
> paid work you do.

That's the plan, yes. It's part of the "portfolio" of (debatably) 
well-written documents I'm building. (You might remember the one a while 
ago on sorting/searching? I still have that.)

> The abstract should say "this is what I'll talk about and why you should 
> bother to buy/download/read the rest of the paper."  The conclusion 
> should say "this is what I covered and I expected you to get, and if you 
> didn't, you should read more carefully.

With most of the stuff I write, it's hard to think of a justification 
for anybody bothering to waste their time reading what I wrote. But the 
conclusion makes sense. ;-)

> Abstract:
> This paper describes a programming technique which is common in 
> functional languages like Haskell but not widely used in imperative and 
> object-oriented languages: the construction of combinator libraries. 
> This powerful technique is introduced by way of the concrete example of 
> a parser for text. Such parsers are common in all programming languages, 
> so the contrast between the mechanisms used in functional paradigms with 
> other paradigms will be easily recognized by programmers unused to 
> functional concepts. Targeting readers for whom combinator libraries are 
> a new concept, simple common syntax is used in the examples, leaving the 
> introduction of Haskell's syntax to the end. No knowledge of Haskell or 
> functional programming is required.

...damn, you're good. o_O

> Conclusion:
> This paper has introduced the reader to the concept from functional 
> programming called a combinator, as well as given an example of how 
> combinators can be collected into libraries to create sophisticated 
> tools from a collection of simple operations. A combinator library for 
> parsing strings is developed and explained. The result has a uniquely 
> functional flavor that is unlike the solutions other paradigms would 
> employ.

You've done this before. :-P

Hmm... clearly I'm going to have to devote some serious attention to my 
existing two documents. ;-)

Post a reply to this message

Invisible wrote:
> - I put all the technical terms in italics and coloured them blue. Does 
> that "work"? Or does it just look like regular emphasis?

That works. Generally, I'd avoid straying from black-and-white for something 
like that, only because people might print it in black and white. Since you 
use italics for emphasis, perhaps boldfacing the first instance of a 
technical term would work well.

> - Does section 3 add anything to the document? Should I make it bigger? 
> Should I take it out?

Either expand on it and include at least three examples, or simply conclude 
section 2 with "by the way, there are other things this works for, like 
financial contracts, expert systems, simulations of physics, ...." or 
whatever it works for.

Expanding section 3 to have three or four examples, but squashing each 
example into just one paragraph without explaining so much would work best, 
in my opinion. I.e., you'd want to say "this works for more than just 
parsers" without turning it into a whole nuther paper.

"""
Combinator libraries are useful for much more than just parsers. Many domain 
models can benefit from a representation of simple operations infinitely 
combinable.

For example, financial contracts are often represented this way. A contract 
might have a value which never changes or which changes as a simple function 
of time. One combination might be summing the values when building a 
portfolio.  Another might be a balloon payment, combining two simple-valued 
contracts by switching from one to the other on a certain date. Another 
might by an option contract, where the combination has one value until 
exercised, after which it has another value. The possible combinations are 
legion, allowing for tremendous flexibility in a way that is still easy for 
a computer to calcuate.
"""

Then do a couple more paragraphs like that. Maybe an expert system, or a 
physical simulation of an electric circuit or something.  I.e., enough to 
give the reader a bunch of examples of the simple operations and the types 
of combinations for a variety of fields. Then you can conclude with

"""
As the reader can see, using functional techniques to combine a variety of 
simple (even trivial) operations in arbitrary combinations is a powerful 
technique capable of modeling a variety of both mathematical and real-world 
domains.
"""

> 
> - What the hell would a real abstract and conclusion actually look like? 

I answered that in another post. I was actually thinking about it during 
breakfast. It isn't just newbies whose minds your writing stretches, altho 
probably not in the way you had intended when you wrote it. :-)

-- 
   Darren New, San Diego CA, USA (PST)
   Insanity is a small city on the western
   border of the State of Mind.

Post a reply to this message

>> - I put all the technical terms in italics and coloured them blue. 
>> Does that "work"? Or does it just look like regular emphasis?
> 
> That works. Generally, I'd avoid straying from black-and-white for 
> something like that, only because people might print it in black and 
> white. Since you use italics for emphasis, perhaps boldfacing the first 
> instance of a technical term would work well.

Yeah, bold is generally discouraged because it tends to stand out too 
much in the middle of the page. (Hmm, and bright blue doesn't?) I've 
also tried slanted on occasion, but it looks too similar to italics. Hmm.

Oh man... you haven't seen the document I'm writing right now! Terms in 
blue, source code in red, source comments in green, type signatures in 
royal blue, keywords in bold\ldots it's a friggin' technicolour rainbow! 
I should probably stop that. ;-)

>> - Does section 3 add anything to the document? Should I make it 
>> bigger? Should I take it out?
> 
> Expanding section 3 to have three or four examples, but squashing each 
> example into just one paragraph without explaining so much would work 
> best, in my opinion. I.e., you'd want to say "this works for more than 
> just parsers" without turning it into a whole nuther paper.

Hmm, yes... OK, I'll aim for that then.

>> - What the hell would a real abstract and conclusion actually look like? 
> 
> I answered that in another post. I was actually thinking about it during 
> breakfast. It isn't just newbies whose minds your writing stretches, 
> altho probably not in the way you had intended when you wrote it. :-)

Yeah, I saw that.

Which time zone do y-- oh, right.

Post a reply to this message

Invisible wrote:
> That's the plan, yes. It's part of the "portfolio" of (debatably) 
> well-written documents I'm building. (You might remember the one a while 
> ago on sorting/searching? I still have that.)

Yes. Cool. I bet folks here would help you polish them up again.

It always helps to go back a month later and read it again, too.

> With most of the stuff I write, it's hard to think of a justification 
> for anybody bothering to waste their time reading what I wrote.

Nonsense.

> ...damn, you're good. o_O

Practice.

In grade school, we started in (IIRC) seventh grade.
7th: Here's the topic. Come back next week with a rough draft of a 2-page paper.
8th: Here's the topic. Come back next week with a rough draft and finished 
2-page paper.
9th: Here's the topic. Come back with an outline for a 2-page paper, and 
write the paper in class.
By 12th grade, it was "here's the topic. You have 20 minutes to turn in an 
outline and finished paper on the subject 2 pages long."

I guess it's unusual, because I keep running into people all thru college 
and life that *can't* sit down with a topic (even one they're familiar with) 
and just start writing somehting interesting about it.

> You've done this before. :-P

*That* is the sort of stuff a PhD teaches you, more than anything technical.

> Hmm... clearly I'm going to have to devote some serious attention to my 
> existing two documents. ;-)

Yes.  And think up some abstracts/conclusions for other papers you might 
want to fill in some day, and ask "would you read this if this were the 
abstract?"

-- 
   Darren New, San Diego CA, USA (PST)
   Insanity is a small city on the western
   border of the State of Mind.

Post a reply to this message

Invisible wrote:
> Yeah, bold is generally discouraged because it tends to stand out too 
> much in the middle of the page. 

Small caps?  Courier?  A san-serif font?

> Oh man... you haven't seen the document I'm writing right now! Terms in 
> blue, source code in red, source comments in green, type signatures in 
> royal blue, keywords in bold\ldots it's a friggin' technicolour rainbow! 
> I should probably stop that. ;-)

When it's lots of colors, people will print it in color. If they just want 
to print a copy of a document where three words are in blue, they might not 
want to spend the money on color.

> Hmm, yes... OK, I'll aim for that then.

Just a suggestion, mind. If you want to turn it into an entire section, that 
works too. I *would* suggest more than one example, since that's the point 
you're trying to make.

> Which time zone do y-- oh, right.

Clever, huh? That's why it's there. ;-)

-- 
   Darren New, San Diego CA, USA (PST)
   Insanity is a small city on the western
   border of the State of Mind.

Post a reply to this message

>> That's the plan, yes. It's part of the "portfolio" of (debatably) 
>> well-written documents I'm building. (You might remember the one a 
>> while ago on sorting/searching? I still have that.)
> 
> Yes. Cool. I bet folks here would help you polish them up again.
> 
> It always helps to go back a month later and read it again, too.

Heh, yeah probably. Maybe I'll go look at that next week.

>> You've done this before. :-P
> 
> *That* is the sort of stuff a PhD teaches you, more than anything 
> technical.

Hehe. In the style of XKCD:

"My hobby: Watching professionals at work, and then saying with 
suspicion 'you've done that before!' "

>> Hmm... clearly I'm going to have to devote some serious attention to 
>> my existing two documents. ;-)
> 
> Yes.  And think up some abstracts/conclusions for other papers you might 
> want to fill in some day, and ask "would you read this if this were the 
> abstract?"

Yeah, but... it's *me*! I'll read anything with computing, algebra or 
pretty pictures in it. ;-)

Post a reply to this message

>> Yeah, bold is generally discouraged because it tends to stand out too 
>> much in the middle of the page. 
> 
> Small caps?  Courier?  A san-serif font?

I've tried smallcaps. I'm not sure I entirely like the effect. Courier I 
reserve for code, and I abhor sans-serif fonts.

>> Oh man... you haven't seen the document I'm writing right now! Terms 
>> in blue, source code in red, source comments in green, type signatures 
>> in royal blue, keywords in bold\ldots it's a friggin' technicolour 
>> rainbow! I should probably stop that. ;-)

"\ldots"? Jesus, I've written far too much TeX today! o_O

> When it's lots of colors, people will print it in color. If they just 
> want to print a copy of a document where three words are in blue, they 
> might not want to spend the money on color.

Heh, yeah.

Maybe I should just make the text a sufficiently light shade of blue 
that it works in greyscale acceptably?

>> Hmm, yes... OK, I'll aim for that then.
> 
> Just a suggestion, mind. If you want to turn it into an entire section, 
> that works too. I *would* suggest more than one example, since that's 
> the point you're trying to make.

I'm going to have to find more examples...

I think I might mention in passing "comparisons to the Composit design 
pattern are left as an exercise for the reader". ;-)

>> Which time zone do y-- oh, right.
> 
> Clever, huh? That's why it's there. ;-)

Do you guys still observe DLS?

Post a reply to this message

Invisible wrote:
> Maybe I should just make the text a sufficiently light shade of blue 
> that it works in greyscale acceptably?

Nah. As it is is fine, as long as you *also* keep the italics.

>> Clever, huh? That's why it's there. ;-)
> Do you guys still observe DLS?

Sadly, yes.

-- 
   Darren New, San Diego CA, USA (PST)
   Insanity is a small city on the western
   border of the State of Mind.

Post a reply to this message

On Fri, 19 Jun 2009 07:16:52 +0100, Orchid XP v8 wrote:

>>>> Why would we point and laugh? It's very clear and well presented.
>>> Really?
>> 
>> Yeah, really.  I read a bit of it (I'm not a hard-core programmer so
>> the topic isn't as much of an interest to me, but I've said it before
>> that you write well and I stand by that assessment).
> 
> Nice that somebody thinks so...

Well, like I said, it's a true statement.  You write well - it's 
something you should consider a strength. :-)

>>>> Nits:
>>> Oh goodie.
>> 
>> Hey, all people can stand to improve on their writing.  Don't take it
>> so personally - it's called "constructive criticism".
> 
> Yeah, I wasn't completely serious about that comment. ;-)

Fair enough, that means you're learning. ;-)

>> As I mentioned
>> before, professional writers usually use an editor as well because when
>> you write tohusands of words, you're bound to mess some of them up.  It
>> happens to everyone. :-)
> 
> You don't even have to write "tohusands" of words. Apparently. :-P

LOL!  Would it help if I said I did that intentionally?  (No, I didn't 
think so, but it couldn't have hurt to ask, could it? <G>)

Jim

Post a reply to this message