Rework of Getting Started Structure #603
Conversation
There was a problem hiding this comment.
Before we can merge the changes we need to fix the formatting issues first. Please apply: https://github.com/mpusz/mp-units/blob/master/CONTRIBUTING.md#unified-code-formatting.
There was a problem hiding this comment.
I totally agree that a project structure can be extracted from this chapter. Splitting into Installation and Usage seems a bit artificial, though (at least in its current shape).
To improve, we first need to define what the "usage" of the library is. I must admit that I have a problem clearly defining it 😉 Is the usage the same as building? If so, then maybe the chapter should be renamed.
For me, "installation" means putting all the necessary files on my local machine. So, we should at least move all of the Conan options and their configuration properties there as well. Also, the "Installation and reuse" chapter should be moved, but it also tells how to build the project, so it is hard to tell where it really belongs.
So maybe we should not split those? Just extract the project structure outside.
To make things shorter, we can also consider providing a "Contributing" chapter and then move the last four chapters there? This, however, somehow collides with the CONTRIBUTING.md file. Should we make both the same? Or should we move things from docs to this file only? However, I noticed that some people are not aware of this file and are not looking for it. We could consider putting everything in the docs and removing the file, but this also breaks some well-established GitHub patterns.
There was a problem hiding this comment.
This, however, somehow collides with the CONTRIBUTING.md file. Should we make both the same? Or should we move things from docs to this file only? However, I noticed that some people are not aware of this file and are not looking for it. We could consider putting everything in the docs and removing the file, but this also breaks some well-established GitHub patterns.
Maybe this calls for generating the HTML from the MD.
There was a problem hiding this comment.
We can do better if we decide that we want both files to have the same content. We do it already for release notes:
$ ls -l docs/release_notes.md
lrwxrwxrwx 1 mpusz mpusz 15 May 16 22:53 docs/release_notes.md -> ../CHANGELOG.md
There was a problem hiding this comment.
Oh, right, the HTML documentation source is already in MD format.
There was a problem hiding this comment.
I would change the order a bit. Before telling people how to install the library, it would be good to show at least what the code looks like and what compilers are needed. Also, not everyone has to install it to start learning it (for example, it is already installed in a production project, and a person just joined the team).
I propose the following order:
Assuming current chapters:
- Introduction
- Quick Start
- Look and Feel
- C++ compiler support (API/ABI)
- Installation
- Project Structure
- Usage
- FAQ
Assuming the "Installation and Usage" and "Contributing" chapters:
- Introduction
- Quick Start
- Look and Feel
- C++ compiler support (API/ABI)
- Project Structure
- Installation and Usage
- Contributing
- FAQ
|
Hi Mateusz ,I am not sure if it is the best choice if someone is totally new in this project, should change the documentation.My opinion is the most expertise one should write the doc.Best FrankMit freundlichen GrüßenFrank Häfelewww.esp8266-01-adapter.deAm 20.08.2024 um 09:34 schrieb Mateusz Pusz ***@***.***>:
@mpusz requested changes on this pull request.
Before we can merge the changes we need to fix the formatting issues first. Please apply: https://github.com/mpusz/mp-units/blob/master/CONTRIBUTING.md#unified-code-formatting.
On docs/getting_started/usage.md:
I totally agree that a project structure can be extracted from this chapter. Splitting into Installation and Usage seems a bit artificial, though (at least in its current shape).
To improve, we first need to define what the "usage" of the library is. I must admit that I have a problem clearly defining it 😉 Is the usage the same as building? If so, then maybe the chapter should be renamed.
For me, "installation" means putting all the necessary files on my local machine. So, we should at least move all of the Conan options and their configuration properties there as well. Also, the "Installation and reuse" chapter should be moved, but it also tells how to build the project, so it is hard to tell where it really belongs.
So maybe we should not split those? Just extract the project structure outside.
To make things shorter, we can also consider providing a "Contributing" chapter and then move the last four chapters there? This, however, somehow collides with the CONTRIBUTING.md file. Should we make both the same? Or should we move things from docs to this file only? However, I noticed that some people are not aware of this file and are not looking for it. We could consider putting everything in the docs and removing the file, but this also breaks some well-established GitHub patterns.
On mkdocs.yml:
I would change the order a bit. Before telling people how to install the library, it would be good to show at least what the code looks like and what compilers are needed. Also, not everyone has to install it to start learning it (for example, it is already installed in a production project, and a person just joined the team).
I propose the following order:
Assuming current chapters:
Introduction
Quick Start
Look and Feel
C++ compiler support (API/ABI)
Installation
Project Structure
Usage
FAQ
Assuming the "Installation and Usage" and "Contributing" chapters:
Introduction
Quick Start
Look and Feel
C++ compiler support (API/ABI)
Project Structure
Installation and Usage
Contributing
FAQ
—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>
|
|
Thanks for your efforts. Inspired by them, I applied the changes to the docs today. Please feel free to let me know if something still can be improved. |
Rework of Getting Started Structure