How To Contribute
Writing proper documentation is hard. We need documentation that is legible, precise, unambiguous and easy to understand.
This section serves to provide basic instructions on how to organize your documentation as well as some style guidelines to keep the documentation style and language consistent across all projects.
Since this is a public repository hosted on GitHub please be careful what parts of Alve Documentation you are exposing in the wild.
Table of Contents
- Set up the project
- Quick guide to have the project up and running locally.
- Familiarize with the project structure
- Though not mandatory to contribute documentation, it is highly recommended to have a quick look on how directories and files are organized.
- Learn the basics of MarkDown
- The kramdown lib is used by default, but there are no major differences from standard or other MarkDown flavors, e.g. GitHub Flavored MarkDown.
- Familiarize with the code style
- Check out how you can enrich your documentation and the rules, conventions and guidelines your contribution has to follow to be accepted.
Once, you have completed the above you may proceed to:
- Add documentation
- Follow the guide to add your documentation pages.
- Submit your documentation
- Create a new pull request.
Project Set Up
First, clone the project:
git clone firstname.lastname@example.org:skroutz/developer.skroutz.gr.git
Then, install the requirements:
Finally, start serving the website locally:
FLAVOR=alve bundle exec middleman server
You may now point your browser at http://127.0.0.1:4567 and view the website.
The project file structure is based on Middleman's skeleton with minor additions for the project's needs.
The following paragraphs describe files and directories you should be familiar with.
This is the core configuration file of the project. Consult the Middleman documentation for the available settings and options you can configure here.
It contains setting files for each flavor as well as common settings across flavors.
data/docs.ymlfile holds the core settings for documentation pages and it is used to generate the navigation structure of available documentations, featured documentations, etc.
It contains the custom helpers built for the project along with task files.
It contains the localization files.
It contains collections of resource files (e.g. code example snippets, API responses, etc.) needed by specific documentation pages.
Contains large code snippets that would be difficult to maintain if placed inline the documentation. Code examples for a document should be placed within a directory with the same name that the documentation lives in. Also, you can have flavored example code snippets if necessary.
See also Add Documentation.
Contains the recorded API responses for each flavor.
This is where all the magic exists. In the
source/ directory lives the content
of the project. It contains the static pages, the documentation pages and the
assets of the project.
- Each document lives in its own directory within
source/localizable/directory. For example, the
source/localizable/analytics/directory contains the documentation for the Analytics project.