Compiling the documentation

[jman-schief]

hey @tarsius

I am back to trying magit-forge again 🙂 ¹ and I would like to contribute a few patches to the docs to make them a bit clearer for newcomers. Would you be open to review patches to the documentation?

When you have some time, it would be great if you could push to git all files needed to locally build the documentation.

Thanks!

Footnotes

1. thanks to the declining quality of the GitHub web interface ↩

[tarsius]

If you have already written those patches, then by all means let me see them.

Otherwise, please know that I have rejected such patches in the past, so you might not want to invest time in work that has a fairly high likelihood of being rejected.

In the past even the "getting started" part of the documentation was more detailed. Users then told me that it would be easier to understand if I "left out (or hide) the irrelevant details". Once I did, other users started telling me that I had left out details that they would have needed to succeed.

I suspect would you intend to suggest is that we push the documentation into either one of these directions. And, regardless of which direction you choose, I am sure for some users that would be an improvement, but at the same time it would make things a bit harder for other users.

IMO what we have now is a good compromise.

I do intend to make things easier eventually. But I intend to do that by making the mechanism simpler, not so much by making just the documentation better.

[jman-schief]

Thanks for sharing your thoughts. I understand the compromise you mention. For the record I already find the documentation of magit-forge excellent!

I just thought very tiny one-sentence clarifications about:

• the docs give for granted some concepts without explaining them anywhere (AFAICS):
  • A "topic" can be a pull request or an issue
  • A "post" is a comment on a pull request or an issue
• The forge-database-file will be by default "forge-database.sqlite" and will be saved in user-emacs-directory

[tarsius]

I wrongly assumed the changes would concern initial setup (token, username ...).

So please submit a pr with your tweaks.

A "topic" can be a pull request or an issue

... or a discussion.