Update and improve documentation

[alrra]

• TOC.md (done in 0efb9fb)
• crossdomain.md (done in 3220cf1)
• css.md (partially done in 0443e50)
• extend.md
  • Update documentation regarding touch icons (see Provide link to Apple's documentation on Touch Icons #1664)
  • Add info on Yandex Themeing meta tags (see Add Yandex Themeing meta tags #1646)
  • Add info on theme-color meta tag (done in 78c84ce)
• faq.md (done in 296b0bb & 8935453)
  • Include information about the recent jQuery announcement (done in 8935453)
• html.md (partially done in: 973b845, 1cac1c9)
• js.md
  • Add information about script from plugins.js(done in 5027eea)
• misc.md
  • Add information about /browserconfig.xml and tile images (done in 001a6c9
    )
  • Add information about robots.txt (done in: 3e3b770 , f134545)
  • Add information about .htaccess (partially done in: ff27f8c)
  • Add information about the web application manifest file
• usage.md (done in 2fcde1e)

[alrra]

Now to close this, and then we're done with v5. :)

[jonathantneal]

Woohoo!

[drublic]

Nice work, Cătălin!

On Tue, Aug 5, 2014 at 6:12 PM, Jonathan Neal notifications@github.com
wrote:

Woohoo!

—
Reply to this email directly or view it on GitHub
#1554 (comment)
.

Hans Christian Reinl
Front-End Developer

Köln - Deutschland
+49 176 44508482

drublic.de
info@drublic.de

[sarukuku]

🎉 v5 🎉

[kiaking]

Hooray! 👍

[ghost]

@alrra you did nice work in the docs ❤️

[coervivek]

Hi All I would like to contribute ,how can I start

[arthurvr]

Hi All I would like to contribute ,how can I start

@coervivek Just start writing. Fork the project, write on a topic in this list (or something else according to h5bp), commit, push and open a PR. For a more in detail explanation check our CONTRIBUTING.md.

[arthurvr]

I would like to send more PRs and finish this, but more specifically what needs to happen? The list above provides just filenames...

[kkirsche]

I am interested in helping with this but would need a better idea of what type of content you would like these to contain. I see some are partially done, but don't specify what would be required to consider them fully complete. Let me know what you'd be interested in for the remaining pieces and I can put something together and send the equiv PRs

[arthurvr]

@kkirsche We would love to have you contributing! All contributions are always welcome. Just FYI, this list of files that we really would like to get done before v5; in fact docs are never really finished, and we're open for all improvements.

As I said, I'm also having a hard time figuring out what really needs to be done. As I said, filenames are just filenames but that's not that helpful in here. Best workflow is to run through a file and its appropriate documentation and see what parts aren't being documented. We don't want to document every byte, but the specialities, best-practices and used techniques.

[alrra]

As I said, I'm also having a hard time figuring out what really needs to be done. As I said, filenames are just filenames but that's not that helpful in here.

The basic idea is to just go through all the documentation related files and:

• update anything that is outdated
• add any missing content (e.g.: things that were added to H5BP, but were not documented)
• simplify and make the existing content more consistent (e.g.: have kinda the same wording)
• move things around to better organize the content and avoid repetition

[roblarsen]

Add docs based on

#1822 and #1783 and #1692 and #1689

[roblarsen]

And... #1963

@coliff this issue outlines some additional documentation tasks. We don't need to get through everything for 6.0, but a good documentation pass with this in mind seems like a good idea.

[coliff]

Cool. I'll work on getting a PR in for the webmanifest.

Also, I noticed that there isn't any mention about the .gitattributes file in the misc.md when there probably should be (.gitignore is mentioned there). I'm not too familiar with exactly how that file works (though did skim-read the docs on the Git site about it: https://git-scm.com/docs/gitattributes).

[coliff]

Doc changes left to do that I can think of....

Usage

• We suggest using a build script such as ant - maybe also suggest Gulp and Grunt as they are more popular?

FAQ

• Remove the ‘Google Analytics at the bottom’ FAQ as it is covered elsewhere in the docs.. Plus performance isn’t really an issue since it loads defer/async
• Remove the section on using Initializr since it isn’t maintained (the project owner confirmed to me today that it is being retired and turned off soon)
• Nicolas’ great post on Quora could be rewritten/updated and included as the FAQ answer to ‘How can I integrate Bootstrap with HTML5 Boilerplate?’

Everything Else

• Below the table of contents change the ‘--’ to ‘---’ (the horizontal rule doesn’t render in Github markdown)
• Add ‘gitattributes’ documentation

Extend

• In the miscellaneous section include a link to the excellent resource of everything that could go in the <head> of your document: http://gethead.info .
• Chrome Mobile web apps section could possibly be removed since that section is covered by w3c manifest.
• Apple Touch icons section needs updating. No need to mention non-retina iPhone and iOS versions lower than iOS 6 for example. I'm not sure the best suggestion on what to include here, but Apple's docs just list 4 sizes now. (https://developer.apple.com/library/content/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html)

[roblarsen]

All good. Some comments:

Remove the section on using Initializr since it isn’t maintained (the project owner confirmed to me today that it is being retired and turned off soon)

👍 I would add a note that we are going to add a command line utility that does some of what initializr offered to v7 (because that's a thing now, I guess, since I said it twice.)

Nicolas’ great post on Quora could be rewritten/updated and included as the FAQ answer to ‘How can I integrate Bootstrap with HTML5 Boilerplate?’

Summarize and link to it?

[roblarsen]

We suggest using a build script such as ant - maybe also suggest Gulp and Grunt as they are more popular?

That section needs a fuller rewrite. Creating a PR for that one.

[roblarsen]

I'm going to close this because, honestly. I just want to get 6.0 out the door and we can continue to tweak the docs.