View this page "Guidelines"

[mattetti]

Here is the guidlines page.

Click on http://groups.google.com/group/merb-book/web/guidelines - or
copy & paste it into your browser's address bar if that doesn't work.

[Rich Morin]

I added a couple of "proposed guidelines" to start things
rolling. Take a look...

-r
--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume r...@cfcl.com
http://www.cfcl.com/rdm/weblog +1 650-873-7841

Technical editing and writing, programming, and web development

[Matt Aimonetti]

The page is still empty... I only see your comment, did you add anything?

- Matt

[Rich Morin]

At 00:14 -0800 12/6/08, Matt Aimonetti wrote:
> The page is still empty... I only see your comment, did you
> add anything?

Yes, but I missed a step in the UI, so it didn't get saved.
Try now.

[Matt Aimonetti]

Works great, thanks. Could you add examples please.

- Matt

On Fri, Dec 5, 2008 at 11:34 PM, Rich Morin <r...@cfcl.com> wrote:

At 00:14 -0800 12/6/08, Matt Aimonetti wrote:

> The page is still empty... I only see your comment, did you
> add anything?

Yes, but I missed a step in the UI, so it didn't get saved.
Try now.

[Damir Zekić]

As for size limits are concerned, maybe we could enforce a level of
readability using Flesch-Kincaid Readability Test[1] or Automated
Readability Index[2]? Google Docs implements both methods (as well as
Flesch Reading Ease).

This could be easily implemented in Ruby and maybe added as a test?

[1] http://en.wikipedia.org/wiki/Flesch-Kincaid_Readability_Test
[2] http://en.wikipedia.org/wiki/Automated_Readability_Index

[Dale Campbell]

Looks good to me. I think either one sentence per line or 80
character lines are both fine choices. I can certainly see how one
sentence per line would make merging quite a bit easier. It would
also be a bit easier to break up the line, if it reaches 80
characters, as opposed to having to edit each successive line if text
is moved down. Should we move this method to the 'Approved' section
of the guidlines page?

On Dec 6, 1:28 am, mattetti <mattAimone...@gmail.com> wrote:
> Here is the guidlines page.
>

> Click onhttp://groups.google.com/group/merb-book/web/guidelines- or

[Damir Zekić]

I've proposed a new guideline for using reference-style links which
makes it possible to shorten lines containing links and also makes the
source text easier to read.

Click on http://groups.google.com/group/merb-book/web/guidelines - or

[Dale Campbell]

+1 to Damir's suggestion. Using this method, it would be fairly
trivial to list out the reference links at the bottom of the rendered
page, as well.

On Dec 6, 8:18 am, Damir Zekić <dam...@gmail.com> wrote:
> I've proposed a new guideline for using reference-style links which
> makes it possible to shorten lines containing links and also makes the
> source text easier to read.
>

> Click onhttp://groups.google.com/group/merb-book/web/guidelines- or

[Rich Morin]

At 06:18 -0800 12/6/08, =?ISO-8859-2?Q?Damir_Zeki=E6?= wrote:
> I've proposed a new guideline for using reference-style ...

Oh yes! I had been chatting with MattA about the possibility
of using something like Interwiki links or variable expansions
to DRY out these URLs, but I had forgotten about this feature
in Markdown. Cool!

[Dale Campbell]

Added some recommendations for inline code examples.

Click on http://groups.google.com/group/merb-book/web/guidelines - or

[Matt Aimonetti]

Let's move all of that to accepted recommendations, I really like Damir's suggestion, I didn't know markdown could do that.

Great job guys,

- Matt

[Dale Campbell]

Done.

[Rich Morin]

I'm willing to implement the line-break guidelines, but I have
some concerns about approach, timing, etc. For instance, I'd be
inclined to add the line breaks _before_ adding the reference-
style links.

How should we approach these sorts of global changes, so as to
minimize the number of errors and the impact on MattA?

[Rich Morin]

Actually, it could be argued that adding the reference-style
links should be done before the line-breaking, in that it will
shorten many of the sentences. However, I'd like to know more
about the technology involved.

Specifically, which parts of a link can we put into the ref?
Is it just the URL or could it also include the text and/or
metadata? And, given these constraints, which parts of a
link _should_ we put into the ref?

[Dale Campbell]

I agree that the updates should be done before adding the reference
links. It would make the transition a bit smoother.

One possibility would be to do the updates late at night and have Matt
merge them first thing in the morning (or immediately following the
push that night). Then he could post a message here (or send pull
requests) alerting everyone to the updates.

I'm a night owl by nature, so if no one else is awake at 3am, I could
tackle it.

On Dec 6, 3:33 pm, Rich Morin <r...@cfcl.com> wrote:
> I'm willing to implement the line-break guidelines, but I have
> some concerns about approach, timing, etc.  For instance, I'd be
> inclined to add the line breaks _before_ adding the reference-
> style links.
>
> How should we approach these sorts of global changes, so as to
> minimize the number of errors and the impact on MattA?
>
> -r

> --http://www.cfcl.com/rdm           Rich Morinhttp://www.cfcl.com/rdm/resume    r...@cfcl.comhttp://www.cfcl.com/rdm/weblog    +1 650-873-7841

[Rich Morin]

At 13:37 -0800 12/6/08, Rich Morin wrote:
> Specifically, which parts of a link can we put into the ref?
> Is it just the URL or could it also include the text and/or
> metadata? And, given these constraints, which parts of a
> link _should_ we put into the ref?

http://daringfireball.net/projects/markdown/syntax#link shows
how to include both the title and the URL in the definition:

[id]: <http://example.com/> "Optional Title Here"

Still dunno whether we can so anything about metadata such as

{: .quote-author}

[Dale Campbell]

Good point, Rich. I'll leave the reference stuff to you guys, since
I'm not fully read up on Markdown's capabilities in that area.

On Dec 6, 3:37 pm, Rich Morin <r...@cfcl.com> wrote:
> Actually, it could be argued that adding the reference-style
> links should be done before the line-breaking, in that it will
> shorten many of the sentences.  However, I'd like to know more
> about the technology involved.
>
> Specifically, which parts of a link can we put into the ref?
> Is it just the URL or could it also include the text and/or
> metadata?  And, given these constraints,  which parts of a
> link _should_ we put into the ref?
>
> -r

> --http://www.cfcl.com/rdm           Rich Morinhttp://www.cfcl.com/rdm/resume    r...@cfcl.comhttp://www.cfcl.com/rdm/weblog    +1 650-873-7841

[Damir Zekić]

I've added guideline for list definition (lazy numbered, nested lists
indented with two spaces).

[Dale Campbell]

Updated with info on the new "whitespace" rake task. (Thanks to Rich
for the original idea).

[mattetti]

Added guidelines for translations