D
D
Dos2020-02-22 04:42:11
Documentation
Dos, 2020-02-22 04:42:11

How to properly document a package on Github Open Source?

Hello. There is a php code that I want to take out to the library for public access. Everything is clear with the code and the package. But now I need to write documentation on the use of this code and the whole project. I studied several symfony repositories of other libraries. Everything is different everywhere and I still have questions:

1. README.md
What structure should be in this file? What is important to put here, and what is better to put in the docs folder? What are the key headings and standards for this file? They do things differently everywhere. Some feed everything in README.md, including versions. For example, it's good if the documentation has icons with the number of downloads and the like.

2. What other files should be added to the package?
In addition to README.md, there are other files. For example, CHANGELOG.md. Again, someone writes the version in the README.

3. What is the structure of the docs folder?
I noticed that some files in this folder have numbers at the beginning of the name. Someone writes them without titles. Some have an example subfolder, some don't. What is the right way to line everything up here?

4. What to describe and how?
Documentation is not a poem. Therefore, documentation should be short and to the point. But everyone has a different understanding and susceptibility. For someone about it will be clear a couple of lines, and for someone to paint on a page. What is usually described in documentation files?

5. Are there standards?
Documentation has been around for a long time. Therefore, for sure there are already some standards for the correct design, as well as writing documentation. Share!

I understand that some questions are absurd, but I would like to understand this issue. I also ask you to share your experience in developing documentation. How do you develop a doc for a package. If there is, then with examples or templates, but which are equal.

If there are any other nuances in the development of documentation, chips, life hacks, tools, services for the development and generation of documentation, I will also watch and hear them once.

Thanks to all!)

Answer the question

In order to leave comments, you need to log in

Didn't find what you were looking for?

Ask your question

Ask a Question

731 491 924 answers to any question