Add docs "Welcome" section #10528

mdo · 2013-09-09T01:39:43Z

Taking a cue from a couple of other projects and a sudden urge to document more than just our framework components, I'm proposing a new docs section. It includes:

Brief history of the framework
List of team members
Callout examples with uses
Community and comms links

/cc @cvrebert @juthilo

* Fixes unrelated typo in readme * Add new Welcome section with history, team, callouts, and community subsections * Redesigns callouts to be a bit lighterweight with colored headings

cvrebert · 2013-09-09T01:46:14Z

getting-started.html

+        <img src="https://2.gravatar.com/avatar/a98244cbdacaf1c0b55499466002f7a8?d=https%3A%2F%2Fidenticons.github.com%2F313701b540df992682dccc8f70dc12a0.png" alt="@fat">
+        <strong>Jacob Thornton</strong> <small>@fat</small>
+      </a>
+      <a class="list-group-item team-member" href="https://github.com/juthilo">


I'm so sorry, I get a little bit encroaching sometimes. 😱

You copied my profile URL into Chris's section. Or were you referring to my weird comment above?

juthilo · 2013-09-09T02:42:44Z

I think this is a great addition, smoothing the edges a little for users coming in directly without knowing about the GitHub project.
Fixes #10314.

mdo · 2013-09-09T02:58:59Z

I'd love some copy editing love btw—forgot to include that in the original comment. I rushed through some of this and spent way too much time on the rest.

cvrebert · 2013-09-09T03:03:49Z

getting-started.html

+    <ul>
+      <li>Read and subscribe to <a href="http://blog.getbootstrap.com/">The Official Bootstrap Blog</a>.</li>
+      <li>Have a question that's not a feature request or bug report? <a href="http://groups.google.com/group/twitter-bootstrap">Ask on the mailing list.</a></li>
+      <li>Chat with fellow Bootstrappers in IRC. On the <code>irc.freenode.net</code> server, in the <a href="irc://irc.freenode.net/twitter-bootstrap">##twitter-bootstrap channel</a>.</li>


The "On..." part is an incomplete sentence fragment.

Should be "on IRC" rather than "in IRC".
We should also gloss what the IRC acronym means.

StevenBlack · 2013-09-09T03:04:21Z

A thought, should this "Welcome" be separate in its own nav item, leaving "Getting Started" as focused, task-centric, and stand-alone?

I say this because History, Core Team, Callouts and Community are not usually associated with getting started.

Also Callouts cries to be expanded to include all the typographical standards and conventions used in the documentation.

See the downside is "getting started" becomes a scroll-scroll-scroll to the meat of the matter, which begins at the Download Bootstrap section. Considering Callouts, I don't see Welcome shrinking but, rather, getting longer.

cvrebert · 2013-09-09T03:06:56Z

getting-started.html

+    <div class="page-header">
+      <h1 id="welcome">Welcome!</h1>
+    </div>
+    <p class="lead">You're looking at the official documentation for Bootstrap, a front-end framework for building on the Web. Get the background story on Bootstrap, useful tidbits about the docs, helpful community links, and more.</p>


Perhaps include the version number in the 1st sentence.

Just a thought: the second sentence could be interpreted as a description for the whole docs. Perhaps include a 'below' to make clear it's only describing the following section's contents?

cvrebert · 2013-09-09T03:21:26Z

I have finished making copyediting suggestions.

juthilo · 2013-09-09T15:58:18Z

README.md

@@ -97,7 +97,7 @@ Editor preferences are available in the [editor config](.editorconfig) for easy
 Keep track of development and community news.

 * Follow [@twbootstrap on Twitter](http://twitter.com/twbootstrap).
-* Read and subscribe to the [The Official Bootstrap Blog](http://blog.getbootstrap.com).
+* Read and subscribe to [The Official Bootstrap Blog](http://blog.getbootstrap.com).
 * Have a question that's not a feature request or bug report? [Ask on the mailing list.](http://groups.google.com/group/twitter-bootstrap)
 * Chat with fellow Bootstrappers in IRC. On the `irc.freenode.net` server, in the `##twitter-bootstrap` channel.


Proposal for this line and the adapted one in getting-started,html:

Chat with fellow Bootstrappers using IRC on the irc.freenode.net server, in the ##twitter-bootstrap channel.

The link is actually irc://irc.freenode.net/#twitter-bootstrap (including the #), because the channel is "non-primary" and has two ##.

Gah, the double hash in the URL doesn't work for me. Might need to ditch the URL.

Huh? There's one hash in the URL and a double hash in the channel name.

juthilo · 2013-09-09T16:00:41Z

Apart from the IRC stuff, nothing else from me.

mdo · 2013-09-09T18:02:01Z

@StevenBlack All good points—appreciate you chiming in.

A thought, should this "Welcome" be separate in its own nav item, leaving "Getting Started" as focused, task-centric, and stand-alone?

Seeing welcome and getting started by each other sounds confusing, hence the inclusion in an existing page.

I say this because History, Core Team, Callouts and Community are not usually associated with getting started.

I suppose we could do some of this on a separate page, e.g. "About". I'll noodle on that.

Also Callouts cries to be expanded to include all the typographical standards and conventions used in the documentation.

Ohhh, good call. I'll get that started by adding the examples and snippets to the list.

See the downside is "getting started" becomes a scroll-scroll-scroll to the meat of the matter, which begins at the Download Bootstrap section. Considering Callouts, I don't see Welcome shrinking but, rather, getting longer.

For sure, definitely seeing that. Downloading and using the code is the most important thing, so we need to balance that. Should we include the "docs intro" in the Getting started page or on this extra "About" page?

cvrebert · 2013-09-09T18:38:24Z

getting-started.html

+    <p class="lead">You're looking at the official documentation for Bootstrap (v{{ site.version }}), a front-end framework for building on the Web. Before diving in, get the background story on Bootstrap, useful tidbits about the docs, helpful community links, and more.</p>
+
+    <h2 id="welcome-history">Brief history</h3>
+    <p>Bootstrap was created at Twitter in mid-2010 by <a href="https://twitter.com/mdo">@mdo</a> and <a href="https://twitter.com/fat">@fat</a>. Prior to being open-sourced framework, Bootstrap was known as Twitter Blueprint. A few months into development, Twitter held its <a href="https://blog.twitter.com/2010/hack-week">first Hack Week</a> and the project exploded. It served as the style guide for internal tools development at the company for over a year before its public release.</p>


"Prior to being open-sourced framework" [sic]. Don't need "framework".

cvrebert · 2013-09-17T04:19:00Z

Still one HTML validation error (well, 4 instances of the same error):

The element <iframe> must not appear as a descendant of the <a> element.

cvrebert · 2013-09-17T04:36:39Z

getting-started.html

+      </a>
+      <a class="list-group-item team-member" href="https://github.com/juthilo">
+        <iframe class="github-btn" src="http://ghbtns.com/github-btn.html?user=juthilo&amp;type=follow" width="120" height="20"></iframe>
+        <img src="http://www.gravatar.com/avatar/bc4ab438f7a4ce1c406aadc688427f2c" alt="@juthilo">


This is @mdo's avatar instead of @juthilo's.

mdo · 2013-10-14T06:21:27Z

Just merged this manually into master as an About page.

juthilo · 2013-10-14T06:53:24Z

Hi, the commits as of this Pull Request somehow landed on Getting started anyway. :)

cvrebert · 2013-10-14T07:32:19Z

This also broke HTML validation: https://travis-ci.org/twbs/bootstrap/builds/12508229

mdo · 2013-10-14T18:31:41Z

Should all be fixed, thanks fellas.

Add Welcome section to docs

7754941

* Fixes unrelated typo in readme * Add new Welcome section with history, team, callouts, and community subsections * Redesigns callouts to be a bit lighterweight with colored headings

cvrebert reviewed Sep 9, 2013
View reviewed changes

cvrebert mentioned this pull request Sep 9, 2013

Link to the mailing list in docs? #10314

Closed

mdo added 2 commits September 8, 2013 19:49

shorter avatar urls

f00e6de

use irc link

d42591e

cvrebert reviewed Sep 9, 2013
View reviewed changes

mdo added 2 commits September 8, 2013 20:39

Merge branch 'master' into docs_welcome

632e3c4

Copy edits from @cvrebert and @juthilo

674e83a

juthilo reviewed Sep 9, 2013
View reviewed changes

mdo added 2 commits September 9, 2013 09:51

dat @juthilo edit

ea99a0a

dat hash

fb9c81f

cvrebert reviewed Sep 9, 2013
View reviewed changes

get HTML closer to validating

e876da4

cvrebert reviewed Sep 17, 2013
View reviewed changes

mdo mentioned this pull request Oct 14, 2013

BS3.0.1 ship list #10050

Closed

mdo closed this Oct 14, 2013

mdo deleted the docs_welcome branch October 14, 2013 06:21

mdo mentioned this pull request Oct 14, 2013

BS3 doc translation list #10113

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs "Welcome" section #10528

Add docs "Welcome" section #10528

mdo commented Sep 9, 2013

cvrebert Sep 9, 2013

juthilo Sep 9, 2013

mdo Sep 9, 2013

juthilo Sep 9, 2013

juthilo commented Sep 9, 2013

mdo commented Sep 9, 2013

cvrebert Sep 9, 2013

cvrebert Sep 9, 2013

StevenBlack commented Sep 9, 2013

cvrebert Sep 9, 2013

juthilo Sep 9, 2013

cvrebert commented Sep 9, 2013

juthilo Sep 9, 2013

mdo Sep 9, 2013

juthilo Sep 9, 2013

juthilo commented Sep 9, 2013

mdo commented Sep 9, 2013

cvrebert Sep 9, 2013

cvrebert commented Sep 17, 2013

cvrebert Sep 17, 2013

mdo commented Oct 14, 2013

juthilo commented Oct 14, 2013

cvrebert commented Oct 14, 2013

mdo commented Oct 14, 2013

Add docs "Welcome" section #10528

Add docs "Welcome" section #10528

Conversation

mdo commented Sep 9, 2013

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juthilo commented Sep 9, 2013

mdo commented Sep 9, 2013

Choose a reason for hiding this comment

Choose a reason for hiding this comment

StevenBlack commented Sep 9, 2013

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cvrebert commented Sep 9, 2013

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

juthilo commented Sep 9, 2013

mdo commented Sep 9, 2013

Choose a reason for hiding this comment

cvrebert commented Sep 17, 2013

Choose a reason for hiding this comment

mdo commented Oct 14, 2013

juthilo commented Oct 14, 2013

cvrebert commented Oct 14, 2013

mdo commented Oct 14, 2013