Expand the E2EE documentation

telenieko commented 8 months ago

Thanks to alphapapa & contributors for such an amazing Matrix client for Emacs. Combined with Beeper I now have all my social networks in one place: Emacs!

We now include as much information as possible about E2EE set up in a separate file (e2ee.org) in order to:

Make up for the lack of documentation from Pantalaimon
Have a place to include tips & tricks about making it work
Have a place to direct users asking about E2EE in Ement.el (and suggesting them to submit updates/additions), like:

Fixes #153

telenieko commented 8 months ago

@alphapapa I have very little knowledge about makem.sh and info pages. But I guess there's something more to be done to have the file included and the link from README work in info pages?

alphapapa commented 8 months ago

The readme is converted to an Info manual by the GNU ELPA build system. (One could also run it locally using ox-texinfo.)

To import one Org file into another when building the Info manual...I think it's possible, but I haven't done it yet myself, so we'll see.

All we need to focus on in this PR is the content. Integration into the rest of the docs can be handled later.

Thanks for contributing this!

telenieko commented 8 months ago

All we need to focus on in this PR is the content. Integration into the rest of the docs can be handled later.

Any feedback on that?

I think I can remove all the TODO entries and submit as is (it is fairly complete without the TODOs) and open a second PR to work on those which may take more time.

So: merge the current document (without TODO entries) now, leave the rest for another moment? Thoughts?

Thanks for contributing this!

you're welcome!

alphapapa commented 8 months ago

My first feedback on the content is that I'd like it to be oriented toward directing the user from start to finish, step-by-step. I think that numbered steps are helpful for telling the user how to proceed and exactly what to do. Looking at the document in its current state, imagining myself to be a user who's installed Ement but nothing else, it's not clear where to begin and what discrete steps to take.

Basically, I just need a user who's successfully installed and configured Pantalaimon to document the discrete, specific, exact steps they followed. Then I'll take care of context and integration.

telenieko commented 8 months ago

[... direct] the user from start to finish, step-by-step. I think that numbered steps are helpful for telling the user how to proceed and exactly what to do. Looking at the document in its current state, imagining myself to be a user who's installed Ement but nothing else, it's not clear where to begin and what discrete steps to take.

I think the new draft covers this a little better. There is now a clear indication of the steps to follow before going into the Hard part, which is client verification.

Let me know your thoughts!

alphapapa commented 8 months ago

@telenieko This seems like good progress. Thanks. Some next steps could be:

[ ] Improve organization of the outline (e.g. Installation, Configuration, Usage, Troubleshooting/FAQ/Tips)
[ ] Add a table of contents
[ ] Make sure content flows sequentially (e.g. mentioning installation after instructions for running is out-of-order).
[ ] Trim content (e.g. anything that could be made more concise or omitted probably should be). Especially, I'd prefer not to have instructions for building and installing Pantalaimon unless absolutely necessary.
[ ] Collect any parts that could also be contributed upstream and consider doing that.

phil-s commented 7 months ago

This seemed like a noteworthy comment from krustyjonez in the chat channel, as the changes for this PR don't include the word dbus:

in addition, there are problems that are platform and distro specific
specifically - you must have dbus working + a GUI agent for dbus notifications
(which can also be a CLI - like Tiramisu - but you can't not have dbus + interactive alerting)

telenieko commented 7 months ago

This seemed like a noteworthy comment from krustyjonez in the chat channel, as the changes for this PR don't include the word dbus:

The current draft mentions the d-bus requirements in the "Requirements (for Pantalaimon)" section.

Note that it is spelled d-bus not dbus source.

you must have dbus working + a GUI agent for dbus notifications

Is that so? I know you must have a session bus, but is the GUI agent a requirement too? Would be good to know.

I have to refactor the current draft and bring some content directly to Pantalaimon, may take some days still! :(

Also, taking note of this gist for future reference.

alphapapa commented 7 months ago

https://github.com/alphapapa/ement.el/pull/242 was recently sent, which appears to document some steps that this guide doesn't mention, like exporting and importing keys. Ideally we should consolidate these guides together.

Also, we should keep in mind that Ement is part of GNU ELPA, so in order for any of these contributions to be included directly, the submitters need to have signed the FSF Copyright Assignment for Emacs. @dionisos2 @telenieko Have you done this? (Apologies if I asked already.)

Thanks.

dionisos2 commented 7 months ago

Hi @alphapapa, I didn’t sign the FSF (and didn’t know what it was before checking).

I think it is better if @telenieko take the information lacking in this document from the other one (so I don’t really need to sign anything), if he is ok with that.

telenieko commented 7 months ago

I'll merge in what's new from #242 and try to keep that around 15 lines, so @dionisos2 can skip the copyright assignment as per his last comment.

I'll go ahead and do mine, as I'm already above the (cumulative) 15 line limit.

TODO list (comes from above):

[ ] Do FSF Copyright Assignment
[x] Improve organization of the outline (e.g. Installation, Configuration, Usage, Troubleshooting/FAQ/Tips)
[x] Add a table of contents
[x] Make sure content flows sequentially (e.g. mentioning installation after instructions for running is out-of-order).
[x] Trim content (e.g. anything that could be made more concise or omitted probably should be). Especially, not to have instructions for building and installing Pantalaimon unless absolutely necessary.
[x] Collect additional notes from #232 and this gist

Also, if possible but not a blocker (because upstream does not appear to be very active):

[ ] Collect any parts that could also be contributed upstream and consider doing that.

telenieko commented 7 months ago

I found this page from GNU that goes deeper into when the Copyright Assignment is needed or not. Leaving it here for reference as the issue came up.

alphapapa commented 7 months ago

@dionisos2 @telenieko I think that's fine as long as you use the ideas from @dionisos2 and explain them in your own words. Thank you!

telenieko commented 6 months ago

Just pinging here. Sorry this is still in my backlog; crazy month!

alphapapa commented 6 months ago

@telenieko Are you pinging me? If so, I guess the to-do list still needs to be done: https://github.com/alphapapa/ement.el/pull/232#issuecomment-1825213173 Or if you're asking someone else to take over, that's fine, just say so clearly, please.

telenieko commented 6 months ago

Hi,

No, Just letting the world know I still plan to finish this!! 😊

Message ID: @.***>

Sorry if that was not clear!

Almost done with the FSF paperwork too.

alphapapa commented 6 months ago

No problem. Thank you. :)

telenieko commented 5 months ago

Just pushed a reviewed document, I think all feedback is in now.

Also sending now the FSF paperwork.

alphapapa commented 5 months ago

Just pushed a reviewed document, I think all feedback is in now.

Also sending now the FSF paperwork.

Thanks, this looks like a big improvement. I'll do some further editing myself, after you confirm the FSF CA is completed and I have time.

Meanwhile, we may want to direct new users here and get their feedback on the document.

telenieko commented 5 months ago

Also sending now the FSF paperwork.

@alphapapa, FSF CA is now complete.

alphapapa commented 4 months ago

Also sending now the FSF paperwork.

@alphapapa, FSF CA is now complete.

Thanks.

For future reference, here's another guide that was just posted on the Pantalaimon tracker: https://github.com/matrix-org/pantalaimon/issues/154#issuecomment-1951591191

alphapapa / ement.el

Expand the E2EE documentation #232