7d0aeeefe5
* Improve format and clarity of the docs [ci skip] While this change produces a lot of git noise by enacting what seems like an arbitrary linewrap on most of the files in the documentation it will result in better version control and tracking of the changes in the documentation. For example, as it currently stands, if one was to make a PR to move a comma in a sentence because each paragraph in most of the files is on a single line, that small change would look in the git history like the author had modified the entire paragraph. In reality, this author just moved a comma. This change also includes a significant number of modifications to the more article-esque docs. Many of these docs were written in a sort of stream-of-conciousness and aren't as easy to read as they could be. Hopefully this is the first of several readability changes. If we could get these docs to a more accessible reading level, we would probably see an increase in contributions. :) * Delegate markdown wrapping to Prettier * Add linewrapping explanation in the docs [ci skip]
2.6 KiB
| title |
|---|
| Contributing to the Docs |
Contributing to DEV's developer documentation
Contributions to the documentation are always appreciated! Thank you for making an effort to improve the developer experience of contributing to the DEV project.
Running the documentation locally
Like DEV, this site is open source and the code is hosted on GitHub. If you find any incorrect information, or a even a typo, we'd love to see a pull request. Follow these steps to get the documentation site running locally.
DEV's documentation is built with GitDocs NodeJS library.
The first step to running the documentations locally is to install the GitDocs
package globally.
With npm:
npm install gitdocs -g
Alternatively, you can use Yarn:
yarn global add gitdocs
Once installed, you should run gitdocs serve from the root of the dev.to
project or from the /docs directory.
gitdocs serve
This will start a server where you can browse the documentation: http://localhost:8000/
If you add new pages or rename existing pages, you'll need to restart the server for those changes to take effect.
Useful links
The docs are a collection of Markdown files that also utilize FrontMatter.
For more information on how to use GitDocs read the GitDocs guide.
Regarding style
Generally speaking, the documentation hosted on this site is informal. There is no need to make things more complicated by writing these articles like a textbooks.
However, it's expected that contributions to these documents are reasonably structured and mostly free of spelling and grammar errors. For this reason, if you submit a PR you might be asked to make changes before your PR is merged.
Prettier is used to autowrap lines in these files to 80 characters. Using 80 characters per line allows us to retain a more specific git history over time. If lines are not wrapped, changing a comma in a paragraph would attribute the entire paragraph to one commit. By line wrapping we are helping git to correctly attribute smaller changes to their commits. This keeps information from getting lost over time.
For more information on effective technical writing, check out writethedocs.org.