April 25, 2018
Installing and running the docs was super quick and easy. I'm very impressed with Yarn, especially in contrast with Ruby package management.
I did get a few of these errors when running locally:
Two or more menu items have the same name/identifier in Menu.
This looks to be the result of the overview/platforms page sharing a title with the Platforms section, same for api/overview.
I'd say that the project is already very friendly and easy to use, but I would make these improvements:
- Add a link to http://localhost:1313/ under "Viewing locally".
- Add the git submodule instructions to CONTRIBUTING.md.
Intro
It looks like this project is brand new. (Congrats!) Once the dust settles, I’d recommend replacing the historical content in the README ("Why this project") with some content to encourage public contributions.
For example:
Welcome to Sensu Docs! This repository is the new home of all Sensu-related documentation and we appreciate your help in maintaining it. You can view the live site at docs.sensu.io.
We ❤️ community contributions. This README will help you get started with the sensu-docs project as a whole. For detail on formatting, layouts and other aspects of adding to or modifying content, please see our project wiki. When you're ready to contribute, please review the contributing guide. If you have any questions, please submit an issue. Thank you!
Link to CONTRIBUTING.md
As a contributor, I want to feel confident that I'm following the project's git and GitHub conventions. Luckily, there's already an awesome doc with this info! I'd recommend linking to CONTRIBUTING.md to point those rule-followers (like myself) in the right direction. (See the example above.)
Branding
Add branding to the README: a Sensu logo, or even better, a logo for the docs or for the Customer Success team.