Re: Wicked app, Domain down, docs up

[Richard Crowley]

On Tue, Mar 4, 2014 at 7:09 AM, Winston Ford <win...@winstonford.com> wrote:
> The devstructure.com domain expired yesterday while my friend Zach and I
> were working on the documentation site.

Matt changed the credit card but did not confirm so it wasn't charged.
This has been fixed now. Thank you for pointing it out!

>
> I have posted my local copy of the docs here:
> http://stratoserver.co:8080/blueprint/
>
> We are working on a pull request unless someone says to stand down.

I appreciate the help and really like the addition of the links to
YouTube. I like syntax highlighting where possible but only the JSON,
Puppet, and Ruby examples are correctly highlighted.

Aesthetically, though, I'd rather keep it simple and closer to the
browser defaults than this proposal.

Richard

[Winston Ford]

Understood.  I really set out to do 2 things: 

1. Shorten the lines to best practice of around 65-70 chars to ease readability.

2. Alleviate mad scrolling back to the toc and man pages as I tried to wrap my head around the documentation.

Here's a stripped down version that just does those 2 things:

http://winstonford.github.io/blueprint/

(Some of the lines in the code blocks do not wrap, but you get the idea.)

Zach was able to select the TOC and MAN sections with nth-of-type css rules so that no edits to the markdown were necessary.  Just now I was playing with the into paragraph copy to try an save a noob like me some time getting a clear picture.

To improve syntax highlighting, we could go github flavored markdown and use fenced code blocks with language identifiers:

https://help.github.com/articles/github-flavored-markdown

-W

[Richard Crowley]

On Mon, Mar 10, 2014 at 8:33 AM, Winston Ford <win...@winstonford.com> wrote:
> Understood. I really set out to do 2 things:
>
> 1. Shorten the lines to best practice of around 65-70 chars to ease
> readability.
> 2. Alleviate mad scrolling back to the toc and man pages as I tried to wrap
> my head around the documentation.
>
> Here's a stripped down version that just does those 2 things:
> http://winstonford.github.io/blueprint/
>
> (Some of the lines in the code blocks do not wrap, but you get the idea.)
>
> Zach was able to select the TOC and MAN sections with nth-of-type css rules
> so that no edits to the markdown were necessary. Just now I was playing
> with the into paragraph copy to try an save a noob like me some time getting
> a clear picture.
>
> To improve syntax highlighting, we could go github flavored markdown and use
> fenced code blocks with language identifiers:
> https://help.github.com/articles/github-flavored-markdown
>

Style-wise, I'd almost be happy to merge this today. Two things still
trouble me: The hover menus obscure some of the menu text. I also
would like the table of contents and manuals to still appear inline
where they logically belong because it's easy to miss the fact that
there even is a table of contents otherwise.

I read through the newly-expanded first paragraph and would like to
see a number of changes there. Please capitalize proper nouns
appropriately, avoid abbreviations like "confs," and use correct
terminology. ("Chef cookbooks" and "Puppet modules" are the preferred
form of those nouns.) It doesn't matter that Blueprint is written in
Python. Documenting that users and groups are not included in
blueprints ("included in" is the preferred language to use) belongs in
the third section, in my opinion, as does the example you've included.

What do you think?

Richard

[Winston Ford]

See my comments inline below:

On Mar 10, 2014, at 1:23 PM, Richard Crowley <r...@rcrowley.org> wrote:

On Mon, Mar 10, 2014 at 8:33 AM, Winston Ford <win...@winstonford.com> wrote:

Understood.  I really set out to do 2 things:

1. Shorten the lines to best practice of around 65-70 chars to ease
readability.
2. Alleviate mad scrolling back to the toc and man pages as I tried to wrap
my head around the documentation.

Here's a stripped down version that just does those 2 things:
http://winstonford.github.io/blueprint/

(Some of the lines in the code blocks do not wrap, but you get the idea.)

Zach was able to select the TOC and MAN sections with nth-of-type css rules
so that no edits to the markdown were necessary.  Just now I was playing
with the into paragraph copy to try an save a noob like me some time getting
a clear picture.

To improve syntax highlighting, we could go github flavored markdown and use
fenced code blocks with language identifiers:
https://help.github.com/articles/github-flavored-markdown

Style-wise, I'd almost be happy to merge this today.  Two things still
trouble me:  The hover menus obscure some of the menu text.

Unclear, would you send a screen shot?  

 I also would like the table of contents and manuals to still appear inline
where they logically belong because it's easy to miss the fact that
there even is a table of contents otherwise.

Agreed. 

I read through the newly-expanded first paragraph and would like to
see a number of changes there.  Please capitalize proper nouns
appropriately, avoid abbreviations like "confs," and use correct
terminology.  ("Chef cookbooks" and "Puppet modules" are the preferred
form of those nouns.)  

Agreed, I was just roughin out copy.  Thx for heads up on Chef, Puppet.

It doesn't matter that Blueprint is written in Python.  

Had a huge discussion re: provisioners with a buddy of mine who uses Chef.  He said he and his team chose it because it's written in Ruby, and they already knew Ruby.  Even if it doesn't matter, I think it's worth 6 chars in the intro.

Documenting that users and groups are not included in
blueprints ("included in" is the preferred language to use) belongs in
the third section,

I would call the absence of users & groups a wall.  A wall is a deal breaker.  When my buddy Zach or I bring up new software, we always ask the other one, "did you find the wall?  how many days in?"  We like to know the wall(s) up front.  If I know it's written in [python] and the wall is [users] I can quickly determine if that wall is a deal breaker, or if I wanna break the wall.  I'm not sayin I'm gonna break that wall, but disclosure mitigates the pain otherwise felt when you find the wall 2 days in.  I think the pain that disclosing the user wall saves is worth the characters needed to express it up top.  

in my opinion, as does the example you've included.

Sure, I suppose it's about walls again.  Even though it may be obvious to someone well versed in provisioners, it was nice when I figured out that the Bluprint wall with apache was htdocs.  Everything up to the /var/www/ dir was automatically created.. the app was installed, the vhosts were added & enabled. Mods added & enabled, but the docs were not.  Which was fine, but I had to find that on my own.  So again, I like to illustrate the walls up front.  Especially now that they are so many provisioners... which admittedly, I know very little about.  

What do you think?

I would still like to go through the markdown and replace unnecessary html header tags with markdown.  h1 tag is primary, so I would downgrade all h1's after Blueprint to an h2.  Also, (mentioned in the previous msg), are you ok with fenced code blocks & language identifiers? The md is less chars than the existing html and code highlighting helps readability quite a bit.

Richard

-- 
You received this message because you are subscribed to a topic in the Google Groups "blueprint-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/blueprint-users/q10j4iB5o_0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to blueprint-use...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.