Update README.md and CONTRIBUTING.md (add links to the wiki)

Thibaut committed 13 years ago

Commit c951b3e1 parent fcaf9872 files · +34 −29Browse files

Unified · Split

2 files

CONTRIBUTING.md +22 −19
README.md +12 −10

 # Contributing to DevDocs
-Wish to contribute? Great. Please review the following guidelines carefully and always search for existing issues before opening a new one. More time spent managing issues means less time spent improving the software.
+Wish to contribute? Great. Please review the following guidelines carefully and always search for existing issues before opening a new one. More time spent managing issues means less time spent improving DevDocs.
-_Note: DevDocs is my first open source project and one which I deeply care about. Please forgive my inexperience and the fact that I may push back on certain things in order to keep the project to my liking. Feedback and advice are always welcome._
 **Table of Contents:**
 1. [Reporting bugs](#reporting-bugs)
 2. [Requesting new features](#requesting-new-features)
-3. [Requesting new docs](#requesting-new-docs)
+3. [Requesting new documentations](#requesting-new-documentations)
 4. [Contributing code and features](#contributing-code-and-features)
-5. [Contributing new docs](#contributing-new-docs)
+5. [Contributing new documentations](#contributing-new-documentations)
-6. [Other contributions](#other-contributions)
+6. [Updating existing documentations](#updating-existing-documentations)
-7. [Coding conventions](#coding-conventions)
+7. [Other contributions](#other-contributions)
-8. [Questions?](#questions)
+8. [Coding conventions](#coding-conventions)
+9. [Questions?](#questions)
 ## Reporting bugs
 For general feedback and ideas, please use the [mailing list](https://groups.google.com/d/forum/devdocs).
-## Requesting new docs
+## Requesting new documentations
 Please do not open issues to request new documentations.
-Use the [Trello board](https://trello.com/b/6BmTulfx/devdocs-documentation) where everyone can vote and contributors can get a feel for what's wished for.
+Use the [Trello board](https://trello.com/b/6BmTulfx/devdocs-documentation) where everyone can vote and contributors can get a feel for what is most wished for.
 ## Contributing code and features
 6. When it makes sense, squash your commits into a single commit.
 7. Describe all your changes in the commit message and/or pull request.
-## Contributing new docs
+## Contributing new documentations
-**Note:** there is currently no documentation on how to create a scraper/documentation. I'm working on it.
+See the [wiki](https://github.com/Thibaut/devdocs/wiki) to learn how to add new documentations.
 **Important:** in order to keep things fast and manageable, only the documentation of popular open source projects will be accepted into DevDocs. As more projects find their way in, the required level of popularity will gradually decrease. Additionally, the documentation's license must permit alteration, redistribution, and commercial use of the work. Software vendors that wish to add commercial software documentation to DevDocs may contact me privately.
 In addition to the [guidelines for contributing code](#contributing-code-and-features), the following guidelines apply to pull requests that add a new documentation:
-* Your documentation must come with a clean and official icon, in both 1x and 2x resolutions (16x16 and 32x32 pixels). This is important because icons are the only thing differentiating search results inside the app. If a project doesn't have an official icon, it won't be accepted into DevDocs—sorry.
+* Your documentation must come with a clean and official icon, in both 1x and 2x resolutions (16x16 and 32x32 pixels). This is important because icons are the only thing differentiating search results inside the app. If a project doesn't have an official icon, it won't be accepted into DevDocs. Sorry.
-* DevDocs favors quality over quantity. Your documentation should only include API/reference documents that most developers may wish to read semi-regularly. By reducing the number of entries you make it easier for people to find other, more relevant entries. _(Note: you're more than welcome to submit pull requests removing seldom-used entries from existing documentations.)_
+* DevDocs favors quality over quantity. Your documentation should only include API/reference documents that most developers may wish to read semi-regularly. By reducing the number of entries we make it easier to find other, more relevant entries. _(Note: you're more than welcome to submit pull requests removing seldom-used entries from existing documentations.)_
 * Try to remove as much content and HTML markup as possible, particularly content which isn't associated with any entries (e.g. introduction, changelog, etc.).
 * Names must be as short as possible and unique across the documentation.
 * The number of types (categories) must be less than 50.
 * It's ok to leave the CSS up to me.
-* Don't modify the icon sprite. I'll do it when merging your pull request.
+* Don't modify the icon sprite. I'll do it after your pull request is merged.
 * Once your documentation is accepted into DevDocs, you'll be expected to maintain it on a regular basis.
+## Updating existing documentations
+Please do not submit a pull request updating the version number of a documentation unless you have verified that it can be generated properly using the current code. Because the source will have changed, the code will likely need a few tweaks.
+To ask that an existing documentation be updated, please use the [Trello board](https://trello.com/b/6BmTulfx/devdocs-documentation) or the [mailing list](https://groups.google.com/d/forum/devdocs).
 ## Other contributions
 Besides new docs and features, here are other ways you can contribute:
-* **Improve words and sentences.** English isn't my first language so if you notice grammatical or usage errors, feel free to submit a pull request—it'll be much appreciated. (Note: American English is the preferred form)
+* **Improve words and sentences.** English isn't my first language so if you notice grammatical or usage errors, feel free to submit a pull request — it'll be much appreciated. (Note: American English is the preferred form)
-* **Write documentation.** Although this task is mainly up to me, any documentation you can write that may help other developers understand and contribute to the code is highly appreciated.
+* **Participate in the issue tracker.** Your opinion matters — feel free to add comments to existing issues. You're also welcome to participate to the [mailing list](https://groups.google.com/d/forum/devdocs).
-* **Participate in the issue tracker.** Your opinion matters—feel free to add comments to existing issues. You're also welcome to participate to the [mailing list](https://groups.google.com/d/forum/devdocs).
 ## Coding conventions
 ## Questions?
 If you have any questions, please feel free to ask on the [mailing list](https://groups.google.com/d/forum/devdocs).

README.md+12−10

 **Table of Contents:** [Quick Start](#quick-start) · [Vision](#vision) · [App](#app) · [Scraper](#scraper) · [Commands](#available-commands) · [Contributing](#contributing) · [License](#copyright--license) · [Questions?](#questions)
-**Note:** I'm in the process of writing more documentation. As DevDocs is quite big, it'll take time. Feel free to [contact me directly](mailto:thibaut@devdocs.io) in the meantime.
 ## Quick Start
 Unless you wish to use DevDocs offline or contribute to the code, I recommend using the hosted version at [devdocs.io](http://devdocs.io). It's up-to-date and requires no setup.
-DevDocs is made of two separate pieces of software: a Ruby scraper responsible for generating the documentation files and indexes, and a JavaScript front-end powered by on small Sinatra app.
+DevDocs is made of two separate pieces of software: a Ruby scraper responsible for generating the documentation files and indexes, and a JavaScript front-end powered by a small Sinatra app.
 DevDocs requires Ruby 2.0. Once you have it installed, run the following commands:
 ## Vision
-DevDocs aims to make reading and searching reference documentation fast, accessible and enjoyable, while aspiring to become the “one stop shop” for all open-source software documentations.
+DevDocs aims to make reading and searching reference documentation fast, accessible and enjoyable. It aspires to become the “one stop shop” for all open-source software documentations.
-The app's main goals are to: keep boot and page load times as fast as possible; improve the quality, speed, and order of search results; maximize the use of caching and other performance optimizations; maintain a clean, readable user interface; support full keyboard navigation; reduce “context switch” by using a consistent typography and design across all documentations; reduce clutter by focusing on a specific category of content (API/reference) and indexing only the minimum useful to most developers.
+The app's main goals are to: keep booting and loading times as short as possible; improve the quality, speed, and order of search results; maximize the use of caching and other performance optimizations; maintain a clean, readable user interface; support full keyboard navigation; reduce “context switch” by using a consistent typography and design across all documentations; reduce clutter by focusing on a specific category of content (API/reference) and by indexing only the minimum useful to most developers.
-**Note:** DevDocs is neither a programming guide nor a search engine. All content is pulled from third-party sources and the project does not intend to compete with full-text search engines. Its backbone is metadata: each piece of content must be identified by a unique, obvious and short string. Thus, tutorials, guides and other content that don't fit this requirement are outside the scope of the project.
+**Note:** DevDocs is neither a programming guide nor a search engine. All content is pulled from third-party sources and the project doesn't intend to compete with full-text search engines. Its backbone is metadata: each piece of content must be identified by a unique, obvious, and short string. Thus, tutorials, guides and other content that don't fit this requirement are outside the scope of the project.
 ## App
 Many of the code's design decisions were driven by the fact that the app uses XHR to load content directly into the main frame. This includes stripping the original documents of most of their HTML markup (e.g. scripts and stylesheets) to avoid polluting the main frame, and prefixing all CSS class names with an underscore to prevent conflicts.
-Another driving factor is the requirement for speed. This is partially solved by maximizing caching (both `applicationCache`, which comes with its own set of constraints, and `localStorage` are used to their full extent), as well as by allowing the user to pick his/her own set of documentations. On the other hand, the search algorithm is currently not very sophisticated because it needs to be fast even searching through 100k entries.
+Another driving factor is performance and the fact that everything happens in the browser. `applicationCache` (which comes with its own set of constraints) and `localStorage` are used to speed up the boot time while memory consumption is kept in check by allowing the user to pick his/her own set of documentations. On the other hand, the search algorithm is currently not very sophisticated because it needs to be fast even searching through 100k entries.
 DevDocs being a developer tool, the browser requirements are high:
 Modifications made to each document include:
 * removing stuff, such as the document structure (`<html>`, `<head>`, etc.), comments, empty nodes, etc.
 * fixing links (e.g. to remove duplicates)
-* replacing all external (not copied) URLs with their fully qualified counterpart
+* replacing all external (not scraped) URLs with their fully qualified counterpart
-* replacing all internal (copied) URLs with their unqualified and relative counterpart
+* replacing all internal (scraped) URLs with their unqualified and relative counterpart
 * adding stuff, such as a title and link to the original document
-These modifications are applied through a set of filters, with each scraper also applying custom filters specific to the documentation. Each document is also passed through a filter whose task is to figure out its metadata, namely its _name_ and _type_ (category).
+These modifications are applied through a set of filters using the [HTML::Pipeline](https://github.com/jch/html-pipeline) library. Each scraper includes filters specific to its documentation, one of which is tasked with figuring out the pages' metadata.
 The end result is a set of normalized HTML partials and a JSON index file. Because the index files are loaded separately by the [app](#app) following the user's preferences, the code also creates a JSON manifest file containing information about the documentations currently available on the system (such as their name, version, update date, etc.).
+More information about scrapers and filters is available on the [wiki](https://github.com/Thibaut/devdocs/wiki).
 ## Available Commands
 The command-line interface uses [Thor](http://whatisthor.com). To see all commands and options, run `thor list` from the project's root.
 Contributions are welcome. Please read the [contributing guidelines](https://github.com/Thibaut/devdocs/blob/master/CONTRIBUTING.md).
+DevDocs's own documentation is available on the [wiki](https://github.com/Thibaut/devdocs/wiki).
 ## Copyright / License
 Copyright 2013 Thibaut Courouble and [other contributors](https://github.com/Thibaut/devdocs/graphs/contributors)