Stopped reading after two sentences because it is grey font on grey background.

On Sunday, 21 July 2013 at 19:45:07 UTC, Walter Bright wrote:
> It's a nice blog! Thanks for doing this.
>
> A stylistic issue:
>
> "These are useful if you want to pass an arbitrary amount of types or values to any kind of template."
>
> It sounds better as:
>
> "These are useful for passing an arbitrary amount of types or values to any kind of template."
>
> I've found in practice that nearly all uses of the word "you" in technical writing are superfluous and it flows better if they are removed.

Thanks, updated.

On Sunday, July 21, 2013 12:40:17 Walter Bright wrote:
> On 7/21/2013 8:43 AM, Gary Willoughby wrote:
> > Please don't let this degenerate into a grammar nazi poasting session, please focus on the article content instead.
> 
> Well, if you do want to be a rebel on capitalization, you have to accept that your audience may get distracted from your message and just see the rebellion :-)

Or worse, just think that you have a lower intelligence level than you actually have.

- Jonathan M Davis

On 7/21/13, Jonathan M Davis <jmdavisProg@gmx.com> wrote:
> Or worse, just think that you have a lower intelligence level than you actually have.

It looks like everyone enjoys being an asshole on the internet these days. Instead of focusing on content these people start min-wars about capitalization. Give it a rest.

On 7/21/2013 2:17 PM, Gary Willoughby wrote:
> Thanks, updated.

Welcs. With my own writing, I'll often write it all out, then grep for "you" and fix them all :-)

On Sunday, 21 July 2013 at 19:45:07 UTC, Walter Bright wrote:
> I've found in practice that nearly all uses of the word "you" in technical writing are superfluous and it flows better if they are removed.

This is why I prefer to use 'thou' when writing documentation. :-P

On 7/21/2013 2:21 PM, Jonathan M Davis wrote:
> Or worse, just think that you have a lower intelligence level than you
> actually have.

I read code, articles, books, etc., all day. There's a million times more content than I could hope to read. So I (and everyone else) needs some sort of filtering mechanism.

A common filter is layout, spelling, grammar, punctuation, capitalization, etc. The more problems there are with that, the more the reader is apt to conclude "this is not worth my time to read" and skip it. Disorganized, sloppy presentation is strongly correlated with disorganized, sloppy thoughts, and who wants to spend time reading it?

Presentation is incredibly important.

Successful authors like Andrei and Scott Meyers spend a great deal of effort worrying about fonts, colors, margins, etc. (a lot more than I do, which is one reason why they are better writers than I). These things matter. I bought a scifi ebook from Amazon a few months ago, and there was a misspelling on every single page. Every one would drop me out of the "zone" in being absorbed in the story, like hitting a pothole on the highway. I didn't buy the sequel because it was so irritating and because I figured the author didn't care about his readers (there were many Amazon reviews about these misspellings, and he still wasn't motivated to fix it).

My brother is in the tech recruiting business. He sees thousands of resumes a week. I asked him once how long he looked at a resume before giving it a thumbs up or [delete]. He said 2 to 3 seconds. Anything with sloppy formatting, misspellings, etc., goes directly to the trash. It's just not worth his time, as there are plenty more resumes where the author did care enough to get it right.


The same, of course, applies to code. If the code is formatted badly, or looks sloppy in any way, the odds go up dramatically that it is full of bugs. We all know this, why shouldn't it apply to writing?

And, of course, you can make a style out of lowercase and no punctuation, like ee cummings. There are always counterexamples! In a sense all of us here are rebels, as the conventional wisdom is to play it safe and use C/C++/Java/C#.

On 7/21/2013 3:24 PM, Adam D. Ruppe wrote:
> This is why I prefer to use 'thou' when writing documentation. :-P

I use "thou" when I'm issuing commandments to my subjects.

On 7/21/13 3:38 PM, Walter Bright wrote:
> On 7/21/2013 2:21 PM, Jonathan M Davis wrote:
>> Or worse, just think that you have a lower intelligence level than you
>> actually have.
>
> I read code, articles, books, etc., all day. There's a million times
> more content than I could hope to read. So I (and everyone else) needs
> some sort of filtering mechanism.
>
> A common filter is layout, spelling, grammar, punctuation,
> capitalization, etc. The more problems there are with that, the more the
> reader is apt to conclude "this is not worth my time to read" and skip
> it. Disorganized, sloppy presentation is strongly correlated with
> disorganized, sloppy thoughts, and who wants to spend time reading it?
>
> Presentation is incredibly important.

Regarding that, this is one awesomely funny flamewar:

http://booksandpals.blogspot.com/2011/03/greek-seaman-jacqueline-howett.html

The flamewar became epic enough to get its own place on Wikipedia: http://en.wikipedia.org/wiki/The_Greek_Seaman


Andrei

On 7/20/2013 2:19 PM, Gary Willoughby wrote:
> Be gentle: http://nomad.so/2013/07/templates-in-d-explained/

http://www.reddit.com/r/programming/comments/1irdjn/how_to_use_templates_in_d/