kylelobo / the-documentation-compendium Goto Github PK

Refer to:

1. commit-message-guidelines - robertpainsi
2. Follow these git commit message guidelines - theserverside
3. Writing good commit messages - erlang/otp

Coming from a background of both tech support and DevOps, the most useful question that I tend to ask on every inbound issue is "What have you tried to resolve the issue yourself?" This is usually followed by "What workarounds are available to you while we work to resolve the issue?" These questions are equally valuable to the reporter and the supporter, and sometimes lead to misunderstandings resolving themselves. Having them as part of the template also discourages "We've tried nothing and are out of ideas" bugs from being filed.

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Italian folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/it

It should involve things such as description, sensors used, s/w requirements, h/w requirements, schematics, how to install a library in the Arduino IDE, baud rate settings, usage etc.

Refer to the various Arduino project documentations for assistance.

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Chinese folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/cn

https://www.makeareadme.com/ is another effort to push for better readmes.

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Korean folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/ko

It should involve things such as description, s/w requirements, h/w requirements, schematics, usage etc.

Refer to the various Arduino project documentations for assistance.

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the German folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/de

Because it auto-generates TOC, and allows to link to header IDs properly.

I have been enlightened. See this README beauty for example: https://github.com/************/linux-kernel-module-cheat/tree/1a739e7866ff7aba0a9924706634335016bc4454#linux-kernel-module-cheat

Rationale at: http://www.************.com/markdown-style-guide/#use-asciidoc

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Russian folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/ru

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the French folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/fr

https://github.com/kylelobo/The-Documentation-Compendium/blob/master/TODO.md

There is no sense in this.

Version controlled TODO lists are a DON'T of documentation.

This project is awesome, includes some useful readme templates.
so I create a VSCode extension that generates README.md, all README templates in VSCode extension based on this project.
Try it, or give me a feedback, thanks. 😄

VSCode marketplace:Read Pattern

https://github.com/kylelobo/The-Documentation-Compendium/blob/d472f574099bf4fec09c2a843857a9b10dc0a40f/CONTRIBUTING.md

This is tutorial on how to use git. This has nothing to do with real-world project contribution guidelines that would be useful in the context of a working git project. There are far better "How to use git" tutorials out there, and this space should describe either

• how to actually contribute to this repo, or
• in general, a proposed education around the politics and conventions of contributing at large

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Spanish folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/es

Ohai, can we also have that as restructured text? I use sphinx to document my projects and rST just goes better with that :)

The minimal README.md template has a link to "Deployment" in the intro of "Getting Started". However, this section is by default not present in the template.

To me, it seems that there are two ways to address this:

1. Rewrite the sentence in "Getting Started" and instead refer to "Usage" of the project rather than "Deployment".
2. Add the "Deployment" section, similarly as it is present in the standard README version.

My take would be to go for (1), as it is probably more in line with the minimalistic nature of this template. However, (2) might be easier, as it requires just copy-pasting from the standard template. Another advantage of (2) would be that minimal and standard deviate as little as possible from each other, making migration between the two easier.

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Portuguese folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/pt

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Hindi folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/hi

Link to the templates: https://github.com/kylelobo/The-Documentation-Compendium#templates

Link to the Japanese folder: https://github.com/kylelobo/The-Documentation-Compendium/tree/master/jp