mirror of
https://github.com/cheatsnake/backend-cheats.git
synced 2024-12-03 15:08:31 +03:00
translated topic about documentation
This commit is contained in:
cheatsnake
parent
5fe2f7c04e
commit
e4647ef017
@ -2222,36 +2222,104 @@ Testing is the process of assessing that all parts of the program behave as expe
|
||||
|
||||
- ### Markdown
|
||||
|
||||
A standard in the development world. An incredibly simple, yet powerful markup language for describing your projects. As a matter of fact, the resource you are reading right now is written with [Markdown](https://en.wikipedia.org/wiki/Markdown).
|
||||
|
||||
- [Markdown cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
|
||||
> A cheatsheet on all the syntactic possibilities of the language.
|
||||
- [Awesome Markdown](https://github.com/BubuAnabelas/awesome-markdown)
|
||||
> A collection of various resources for working with Markdown.
|
||||
- [Awesome README](https://github.com/matiassingers/awesome-readme)
|
||||
> A collection of beautifull README.md files (this is the main file of any repository on GitHub that uses Markdown).
|
||||
- Markdown for your notes
|
||||
> Markdown is not only used for writing documentation. This incredible tool is great for learning - creating digital notes. Personally, I use [Obsidian editor](https://obsidian.md/) for outlining new material.
|
||||
|
||||
<details>
|
||||
<summary>🔗 <b>References</b></summary>
|
||||
|
||||
</details>
|
||||
1. 📺 [**How To Write a USEFUL README On Github** – YouTube](https://youtu.be/E6NO0rgFub4)
|
||||
2. 📺 [**Obsidian As A Second Brain: The ULTIMATE Tutorial** – YouTube](https://youtu.be/WqKluXIra70)
|
||||
</details>
|
||||
|
||||
<div align="right"><a href="#top">Contents ⬆️</a></div>
|
||||
|
||||
- ### Documentation inside code
|
||||
|
||||
For every modern programming language there are [special tools](https://en.wikipedia.org/wiki/Documentation_generator) which allow you to write documentation directly in the program code. So you can read the description of methods, functions, structures and so on right inside your IDE. As a rule, this kind of documentation is done in the form of ordinary comments, taking into account some syntactic peculiarities.
|
||||
|
||||
- Why do you need it?
|
||||
> To make your work and the work of other developers easier. In the long run this will save more time than _traveling through the code_ to figure out how everything works, what parameters to pass to functions or to find out what methods this or that class has. Over time you will inevitably forget your own code, so already written documentation will be useful to you personally.
|
||||
- What does it take to get started?
|
||||
> For each language, it's different. Many have their own well-established approaches:
|
||||
>
|
||||
> - [Docstring](https://peps.python.org/pep-0257/) for Python.
|
||||
> - [JSDoc](https://github.com/jsdoc/jsdoc) for JavaScript.
|
||||
> - [Godoc](https://go.dev/doc/comment) for Go.
|
||||
> - [KDoc и Dokka](https://kotlinlang.org/docs/kotlin-doc.html) for Kotlin.
|
||||
> - [Javadoc](https://en.wikipedia.org/wiki/Javadoc) for Java.
|
||||
> - And look for others on request: `documentation engine for <your lang>`.
|
||||
|
||||
<details>
|
||||
<summary>🔗 <b>References</b></summary>
|
||||
|
||||
</details>
|
||||
1. 📺 [**How To Use Developer Documentation** – YouTube](https://youtu.be/s1PLS3SQHQ0)
|
||||
2. 📺 [**How to use JSDoc - Basics & Introduction** – YouTube](https://youtu.be/Nqv6UkTROak)
|
||||
3. 📺 [**Godocs - Effortless documentation for your go packages** – YouTube](https://youtu.be/80VT3xexcWs)
|
||||
</details>
|
||||
|
||||
<div align="right"><a href="#top">Contents ⬆️</a></div>
|
||||
|
||||
- ### API Documentation
|
||||
|
||||
Easy-to-understand documentation will allow other users to understand and use your product faster. Writing documentation from scratch is a tedious process. There are common specifications and auto-generation tools to solve this problem.
|
||||
|
||||
- [OpenAPI](https://en.wikipedia.org/wiki/OpenAPI_Specification)
|
||||
> A specification that describes how the API should be documented so that it is readable by humans and machines alike.
|
||||
- [Swagger](https://swagger.io/)
|
||||
> A set of tools that allows you to create convenient API documentation based on the OpenAPI specification.
|
||||
- [Swagger UI](https://swagger.io/tools/swagger-ui/)
|
||||
> A tool that allows you to automatically generate interactive documentation, which you can not only read but also actively interact with it (send HTTP requests).
|
||||
- [Swagger editor](https://editor.swagger.io/)
|
||||
> A kind of playground in which you can write documentation and immediately see the result of the generated page. You can use YAML or JSON format file for this.
|
||||
- [Swagger codegen](https://swagger.io/tools/swagger-codegen/)
|
||||
> Allows you to automatically create API client libraries, server stubs and documentation.
|
||||
|
||||
<details>
|
||||
<summary>🔗 <b>References</b></summary>
|
||||
|
||||
</details>
|
||||
1. 📺 [**REST API and OpenAPI: It’s Not an Either/Or Question** – YouTube](https://youtu.be/pRS9LRBgjYg)
|
||||
2. 📺 [**Swagger API documentation with Django REST Framework** – YouTube](https://youtu.be/fbIFdWj8PsY)
|
||||
3. 📺 [**NodeJS Swagger API Documentation Tutorial Using Swagger JSDoc** – YouTube](https://youtu.be/S8kmHtQeflo)
|
||||
4. 📺 [**Golang Microservices: REST APIs - OpenAPI / Swagger** – YouTube](https://youtu.be/HwtOAc0M08o)
|
||||
</details>
|
||||
|
||||
<div align="right"><a href="#top">Contents ⬆️</a></div>
|
||||
|
||||
- ### Static generators
|
||||
|
||||
Over time, when your project grows and has many modules, one README page on GitHub may not be enough. It will be appropriate to create a separate site for the documentation of your project. You don't need to learn how to make it, because there are many generators for creating nice-looking and handy documentation.
|
||||
|
||||
- [GitBook](https://www.gitbook.com/)
|
||||
> Probably the most popular documentation generator using GitHub/Git and Markdown.
|
||||
- [Docusaurus](https://docusaurus.io/)
|
||||
> Open-source generator from Facebook (Meta).
|
||||
- [MkDocs](https://www.mkdocs.org/)
|
||||
> A simple and widely customizable Markdown documentation generator.
|
||||
- [Slate](https://slatedocs.github.io/slate)
|
||||
> Minimalistic documentation generator for REST API.
|
||||
- [Docsify](https://docsify.js.org)
|
||||
> Another simple, light and minimalistic static generator.
|
||||
- [Astro](https://astro.build/)
|
||||
> A generator with a modern and advanced design.
|
||||
- [mdBook](https://rust-lang.github.io/mdBook/)
|
||||
> A static generator from the developers of the Rust language.
|
||||
- [И другие...](https://jamstack.org/generators/)
|
||||
|
||||
<details>
|
||||
<summary>🔗 <b>References</b></summary>
|
||||
|
||||
</details>
|
||||
1. 📺 [**Build a Markdown Documentation Site with Docusaurus (Step-by-Step)** – YouTube](https://youtu.be/2R53Y7eP45k)
|
||||
2. 📺 [**Create template layouts for your HTML with Astro SSG** – YouTube](https://youtu.be/o7iQAF2EvUU)
|
||||
</details>
|
||||
|
||||
<div align="right"><a href="#top">Contents ⬆️</a></div>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user