Formatted Documentation

![Separator]

[ Please Check The **Preview** ][Preview]

Disable unused Widgets:
- Packages
- Releases
Disable unused Tabs:
- Projects
- Actions
Why not to use GitHub Wiki

Move content into documentation folder.

I would be happy to help you with that.

General formatting / spacing
Moved addon documentation into dedicated file
Placed documentation into dedicated folder
Added quicklinks
Named included addons

If you have any questions.
In case you do not agree with some of the changes made in this PR, please first let me know about them, before disregarding it entirely so we can possibly find a middle ground and have it not go to waste.

## ![Badge Robot]
No, I'm not a robot. Yes, you are not the first. I just made a PR template.

## ![Badge Info] If you want to know more about **Markdown** check out
[![Button MarkedDown]][MarkedDown]

![Separator]

That's a quite large pull request for something we did not ask for and that wasn't discussed in any issue before. I appreciate the effort, but I don't think I like all of it.

Some points:

improving the formatting of the README is in principle welcome. It is currently quite basic.
Including HTML in a Markdown file is wrong. Markdown is made to be read by humans. Rendering it to HTML is optional. In a repo like that the files will probably often be read in a checkout, maybe even in a terminal
I like the README.md and INSTALL.md standard layout. We can use a docs folder when there is more documentation than the two files.
I would need to test some of the formatting for real, but I think for example keeping the links to the addons near the name is useful when reading the file without rendering it to HTML. I would also need to test it in a markdown rendering and look at it as text file.

So I guess I would happy about some of the restructuring and rewording in the readme, but without HTML and probably without splitting up the links.
Some less important links could be split up, but on the other hand I don't think anyone wanting to run a Django project needs a link to the python homepage anyway and it only makes the readme longer.

Reply

That's a quite large pull request

You call 3 (4) file changes a large PR?

for something we did not ask for

Contributing

Help to improve the text and instructions

that wasn't discussed in any issue before.

If you wanted that, you should have written a CONTRIBUTING.md file then.

Including HTML in a Markdown file is wrong. Markdown is made to be read by humans. Rendering it to HTML is optional. In a repo like that the files will probably often be read in a checkout, maybe even in a terminal

'Wrong'? Sorry, are you the ministry of truth by chance?

You want to tell me that \<br> is so horribly unreadable compared to standard markdown things such as links, headers, etc.. ?

I like the README.md and INSTALL.md standard layout.

I wouldn't call INSTALL.md a standard, more of a leftover ugly duckling.

We can use a docs folder when there is more documentation

Sorry, but you may have missed a section in my PR..

I suggested to move the wiki content ( documentation ) into the docs folder as well.

than the two files.

Well the root folder with 1 , 2 , ... 8 (9) python files might think otherwise ..

I would need to test some of the formatting for real, but I think for example keeping the links to the addons near the name is useful when reading the file without rendering it to HTML. I would also need to test it in a markdown rendering and look at it as text file.

Sure, but are you certain you are pandering to the right audience?

If you so care about plain readabiliy, you might as well add an alternate .txt version that only uses manual formattig like in the good old days.

I don't think anyone wanting to run a Django project needs a link to the python homepage anyway and it only makes the readme longer.

Just because you think users are gonna be fine and even if they are, that doesn't mean that having the resource conveniently linked isn't the better way of doing things.

Changes

So I guess I would happy about some of the restructuring and rewording in the readme, but without HTML and probably without splitting up the links.

Despite my above responses, I will happily 'adjust' it to whatever least ugly version we can come to.

That is, if you didn't already close it.

I appreciate your work, but I don't want all changes. And I dislike your tone.

I see that you did a lot of work. You did quite a few things that I probably do not want, and this is wasted work that would not have been done if you had asked if it is wanted.

You call 3 (4) file changes a large PR?

I think it is hard to split. I probably would cherry-pick some changes, but it doesn't look like I can just use some of the commits (to keep attribution and everything) as they depend on each other and some in the chain include the unwanted parts.

If you wanted that, you should have written a CONTRIBUTING.md file then.

I don't think I really need it for a small project. People can open issues for suggestions (even without wanting to implement them themself), people can send pull requests they think match, and people can fork the project. I even encourage forks that include things that aren't the focus here, i.e., larger changes of the Firefox UI or personal preferences that will not benefit the average user. Some of them could probably be an own profile (see the profiles folder for a proof of concept) and then could be included.
When I dislike a pull request, I am, on the other hand, free to give feedback, ask for changes or close it. I'd prefer not to waste people's time, so asking before making large changes is a good idea.

'Wrong'? Sorry, are you the ministry of truth by chance?

That's what I mean with the tone. This is an open-source project. I do it for fun and to benefit people. I invested a lot of time, I didn't get a single cent for it. I run a hosted version of it without ads. And now I get talked to in such a rude tone because I give feedback on suggested changes. Do you really think that's appropriate? Pay some respect to the maintainer of the project you like to contribute to.
I am really open to things and leave many issues I am not sure about open for further discussion, and I didn't close this pull request right away or decline the changes completely but gave my feedback on what I like and don't like for further discussion. But such a tone doesn't motivate me to get the PR down to something I'd like to have in the repo.

You want to tell me that
is so horribly unreadable compared to standard markdown things such as links, headers, etc.. ?

Markdown is a text format. Look at your files in vim, notepad.exe, or any other standard text editor. Doesn't it look ugly? Especially
should create a linebreak but is noise in a text file, which doesn't have the effect as a linebreak in Markdown.

By the way, if you like to include a linebreak (and not a paragraph), you can, as I did in this pose several times, end the previous like with two spaces.

I wouldn't call INSTALL.md a standard, more of a leftover ugly duckling.

You can have this opinion. But I do not share it. And if you want to convince me, you need to try to convince me and insult me. A post like this won't get you anywhere.

Sorry, but you may have missed a section in my PR..

I skimmed it first (here it is late at night, don't expect a full review at this time). It seemed to me that you moved README and INSTALL files into a documentation subfolder? As said, I gave feedback as a basis for a discussion, so we could get the PR to something I would merge.

Sure, but are you certain you are pandering to the right audience?

I think it's fine that way. I appreciate a bit better structure and improvements on the wording and maybe expanding it a bit, but I don't like to get from Markdown to a half HTML file. I think supporting HTML is an un-feature of Markdown because it ruins the whole "A textfile that looks a bit better when rendered to HTML/RTF/..." idea.

Just because you think users are gonna be fine and even if they are, that doesn't mean that having the resource conveniently linked isn't the better way of doing things.

That's your opinion. But this is not a forum whose style is the better, but an open source project I put online because I like to open source my hobby projects. I do this for fun, and most of the code is written and maintained by me. I've got many good suggestions and a lot of help from the community, but all these people were friendly and open for discussion, suggestions, and change requests.

You seem to think you have some right that I should absolutely use your changes because they are, by definition, the best way to do it. I disagree and don't think I like to merge all the changes. I posted a few bullet points of what I do not like, so we could possibly get the PR to something I will merge.

But it won't get anywhere when you try to convince me with a rude tone like "Sorry, are you the ministry of truth by chance?" and phrasing personal opinions like "I wouldn't call INSTALL.md a standard, more of a leftover ugly duckling."

Despite my above responses, I will happily 'adjust' it to whatever least ugly version we can come to.

I didn't close it, but it doesn't look like you really want to collaborate but rather force your ideas on me. Maybe you re-read your post and think about if the tone is really appropriate for when you have a suggestion and try to convince someone that it's a good idea. I am not sure if it works with other people, but for me, it rather kills the motivation to work with you toward a version we both like.

A few more feedback points:

I think you may have gotten the part about addons wrong. At least you included a button that looks like you think it's about addons to the profilemaker, but the list is about Firefox addons, which are data that is put into ZIP files generated by the app.
Pages like your Installation.md contain a lot of white space. Look at the large gap before the two lonely bullet points "VirtualEnv" and "Python" in the requirements section.
The formatting of the installation steps looks quite nice. I am unsure if it would be more useful in one long code block (one could copy&paste it), and the first step could have a line break instead of a semicolon.
You seem to use very short lines. "Manually edit the following file as described in the manual steps:" for example, does not require a line break. It makes the document longer, and the line break there looks rather unintentional, but you also use such short lines in the main README.
While having some structure is nice, a section, like "Source Code", for a single sentence is overkill. A section should be a whole section, not a single sentence that is short enough that it could almost be a bullet point.
Minor point: "You are welcome to create a "/profiles/" for settings that are outside of the project's scope or alternatively just fork the project." -- here, you could have used a named link to the folder, as "a profile" should be singular there, and it probably reads better without the slashes (but I see the appeal to show that profiles live in a folder).

God, I hate long replies, but here we go . .

I think it is hard to split. I probably would cherry-pick some changes, but it doesn't look like I can just use some of the commits (to keep attribution and everything) as they depend on each other and some in the chain include the unwanted parts.

I would just make a branch, change the things you asked for and squash everything down into a 'Formatting Commit' or something.

I invested a lot of time, I didn't get a single cent for it.

Same as me, so far.

I run a hosted version of it without ads.

Well maybe you should have just run it with GitHub actions for free then.

And now I get talked to in such a rude tone because I give feedback on suggested changes. Do you really think that's appropriate? Pay some respect to the maintainer of the project you like to contribute to.

You can't even take a joke?

Maybe you are forgetting that you denied my whole way of working with your sentiment to begin with .. Including HTML in a Markdown file is wrong. ..

By the way, if you like to include a linebreak (and not a paragraph), you can, as I did in this pose several times, end the previous like with two spaces.

I know, but I choose not to, as it isn't visible to the editor of the document as with break tags, if you'd rather have it for your text based view, I can change it to that.

And if you want to convince me, you need to try to convince me and insult me.

If I wanted to insult you I would talk differently, I can assure you that, though, you on the other hand might want to proofread what you send out to the world as well~

You seem to think you have some right that I should absolutely use your changes because they are, by definition, the best way to do it.

I don't, but I will try to defend my work as it is and come to the closest middle-point I can find.

I didn't close it, but it doesn't look like ..

Well considering your first reply I wasn't exactly motivated to engage considering your questioning of most of the changes.

'A few more points' section

I think you may have gotten the part about addons wrong. At least you included a button that looks like you think it's about addons to the profilemaker, but the list is about Firefox addons, which are data that is put into ZIP files generated by the app.

No, I did think they were FF addons / extensions, why did you think I got them wrong?

Pages like your Installation.md contain a lot of white space. Look at the large gap before the two lonely bullet points "VirtualEnv" and "Python" in the requirements section.

Overall that is on purpose, instructions should be cramped together.

Having them spaced like in actual instruction manuals let's the user comprehend what they are currently working on and not have to re-read because they aren't sure where they left off.

In the case of the requirements section, I can remove that first whitespace if you want.

The formatting of the installation steps looks quite nice. I am unsure if it would be more useful in one long code block (one could copy&paste it), and the first step could have a line break instead of a semicolon.

Well since the steps are supposed to show the users what's happending I would keep them separate, if you want to have a one and done code bit, consider making a separate file with comments.

You seem to use very short lines. "Manually edit the following file as described in the manual steps:" for example, does not require a line break. It makes the document longer, and the line break there looks rather unintentional, but you also use such short lines in the main README.

Humans on average can only comprehend 60 columns, that goes for text as much as code.

Getting people to stop at 100 columns is hard enough, sadly.

I choose to wrap lines early for stylistic reasons, such that they are of equal length, which helps the user as well ( simpler shape of the overall text )

While having some structure is nice, a section, like "Source Code", for a single sentence is overkill. A section should be a whole section, not a single sentence that is short enough that it could almost be a bullet point.

It's not about how many chars, words, sentences there are in a section, it's about structuring the topics, so I don't agree with that sentiment.

By that logic I would have to advice you to simply split the sentence up or write some more..

Minor point: "You are welcome to create a "/profiles/" for settings that are outside of the project's scope or alternatively just fork the project." -- here, you could have used a named link to the folder, as "a profile" should be singular there, and it probably reads better without the slashes (but I see the appeal to show that profiles live in a folder).

Yes, I wasn't sure which version I wanted to use here.

And yes, I know it was technically wrong, though funnily enough, so was the original README at that same position.

God, finally done ..

Okay, that sounds a bit more reasonable now. See, you're suggesting changes. That's basically asking me if I'd like to have them. The more you prepare before asking, the more may be wasted when I do not want to have them.

I could answer every single point, but I don't feel like I should defend my design choices, and you seem to have strong opinions on issues that I disagree with.

I close this pull request now. I appreciate that you took your time, but sadly I don't want to use the result. I'll keep as a takeaway that the README can use some love, but I think more of formatting it and adding a bit more description than trying to create a fully styled homepage in a Markdown file.

allo- / ffprofile