Hello,
I went through the project ideas page of the GNU Mailman's page for GSoD'19 thoroughly and am interested in working on improving the Developers' Documentation for Postorius and Hyperkitty. I also went through the responsibilities mentioned by Steve and have few doubts.
Is there any user guide/support page on how to use the mailing list explaining all the features of Postorius and Hyperkitty? For example, how to manage subscription, how to manage lists. what does activity summary means, what does the graph represents, what do the different roles represent, what is the difference between an owner, a moderator and a member. Being new to mailing list, I feel that people may face these issues and having a proper documentation on how to properly utilize the platform will be a great win.
During my GSoC days, I failed several issues while setting up the project locally on my machine. It became very difficult to test everything from end to end. And I feel that there should be documentation on how to test the complete application from end to end. For example, I faced difficulty in configuring Mailman to Hyperkitty or how to inject a mail to a thread in Mailman3 and had to go through many discussions to get it running. It took many days to get everything running on the web interface. I feel that we should go through the mail archives of last few years GSoC season and should work on those areas where most of the developers felt difficulty.
Let me know your inputs.
Thanks, Aditi
ᐧ
Hello Aditi!, I am a fellow contributor in this organization under GSoC programme. Great to have you onboard with us.
Technically we have each feature defined in "Models" section[1] of the docs under GNU Mailman. That being said, an effective doc page containing the use-cases of these features in postorius and hyperkitty is not there at all. We can definitely add them under the respective doc but I do not know about the priority of this task. Also, what I noticed is that the respective docs of Postorious and Hyperkitty are a little less detailed, we can do some improvements ( like adding these type of use-cases ) and I would love to personally help if some GSoD folks pick it up but again I do not know the priority of this.
One more thing ( this may be nitpicking but I want to clear my point here instead of just keeping it to me ), the docs the name "GNU Mailman" but it then mentions it is technically the "Mailman Core" part and the rest is on separate docs, it took me for a while to get the hang of what it was exactly, Can we bundle this under one "GNU Mailman" and it contains 5 bundles "Suite", "Postorius", "Hyperkitty", "Core", "MailmanClient"? I think this reduces redundancy in the docs and makes them more comprehensible.
Or is the current approach more suitable for reasons that I would definitely like to learn and know. I would definitely like some pointers on this.
Technically the section "Testing mailman 3" of this page[2] will tell you how to run tests and you can see what the tests are under the "tests" folder of the specific repo, ( just see the .rst files ). In case of "facing several issues while setting up locally...", I believe asking in the this mailing list is the best option and if we recognize the problem to be common or something specific, we can write it under a section or at least in some sort of FAQs which are already present here[3]. For the problems which you feel in which "most of the developers felt difficulty," we can definitely look up the archives and make some FAQ out of those problems ( if the FAQ is not there already ), I am up for helping this if anyone of you GSoD folks picks it up.
[1] : https://mailman.readthedocs.io/en/latest/src/mailman/model/docs/model.html [2] : https://mailman.readthedocs.io/en/latest/src/mailman/docs/contribute.html [3] : https://wiki.list.org/DOC/Frequently%20Asked%20Questions
Cheers!
Hi Aaryan,
Thank you for your descriptive response.
Yes, I have gone through the "Models" section of the docs but it is more developer centric. I am suggesting that we should have docs explaining the use cases of all the features from both developer and user perspective.
I want to know if we can add this as a task as well. Also, it would be helpful to make the docs more detailed for Postorius and Hyperkitty as most of them are outdated. Also, it would be great if we can add the complete architecture of the project somewhere to give a overview of the project to the new developers who are interested in contributing.
I agree with this as it will reduce the effort , a new developer has to go through for the first time. It's very difficult for the maintainers and the mentors to reply to each and every thread on the mailing list and having a good documentation will certaily lessen the number of doubts being asked in the mailing groups.
Yes , now I am aware of it but personally, I faced these issues while setting it up on my local for the first time. I think creating a FAQ will be a good idea but again I am not sure the priority of this.
Also, I would like to know if I should post my proposal here so that the mentors can review it and give more insights on what is expected.
Thanks and Regards, Aditi ᐧ
On Sun, Jun 2, 2019 at 10:51 PM Aaryan Bhagat <aaryanbhagat377@gmail.com> wrote:
Hi Aditi,
Thanks for your interest on Mailman docs. I am posting some of my random thoughts and hope it helps :)
I have written a document on deploying to AWS using Docker < https://xiaoxing.us/2018/01/01/deploy-mailman-3-on-aws-using-docker/>, which I think is also applicable to local installation - just skip the SES configuration.
So, we can roughly categorize our users into three types: the Mailman Core, Hyperkitty and/or Postorius;
- Users of mailing list: They may not know what's Mailman Suite but using
- Maintainers of mailing list: They install mailman and they know what's that, but may not want to write a line of code;
- Developers of Mailman: They know much about programming and are willing (or forced) to write code on Mailman.
Think about it, as different type of user, what kind of document do you want? For example, as a normal user (Type 1), you will be happy if you see detailed description on how to operate the archiver, how to manage the subscription (though the web interface is quite friendly); and as a developer, you will need instruction on how to setup the dev environment and start working.
If you look at our Mailman GSoD page, there are two ideas: maintainer or a developer - but make it easy since maintainers may not know
- Instructions for Migrating from Mailman 2 to Mailman 3: That can be for a
how to code in Python.
- Developers' Documentation for Hyperkitty/Postorius: That's definitely for a developer, type 3.
And Aaryan has mentioned before, our documents on rtd are not that clear, and you may look back at this < https://mail.python.org/archives/list/mailman-developers@python.org/thread/W...> for Abhilash's words so you will
Actually, the Models section of the docs is not for developers of Mailman - it is for maintainers. If you want to create a tons of new lists, using cli is a good way. It may look like some very technical things though. When we are talking about "GNU Mailman", it is highly possible that it is about the whole project (including Mailman Core, Hyperkitty and so); and "Mailman" for "Mailman Core".
Personally, I think our docs need a reorder - you may think about it but it is going to be a big project.
And last, yes you are welcomed to post your proposal here so we can help review or give suggestions :)
Looking forward to your contributions.
Yours truly, Xiaoxing Ye http://www.linkedin.com/in/yexiaoxing
On Wed, Jun 5, 2019 at 11:52 PM ADITI GUPTA <aditi.medha96@gmail.com> wrote:
Hello Aditi!, I am a fellow contributor in this organization under GSoC programme. Great to have you onboard with us.
Technically we have each feature defined in "Models" section[1] of the docs under GNU Mailman. That being said, an effective doc page containing the use-cases of these features in postorius and hyperkitty is not there at all. We can definitely add them under the respective doc but I do not know about the priority of this task. Also, what I noticed is that the respective docs of Postorious and Hyperkitty are a little less detailed, we can do some improvements ( like adding these type of use-cases ) and I would love to personally help if some GSoD folks pick it up but again I do not know the priority of this.
One more thing ( this may be nitpicking but I want to clear my point here instead of just keeping it to me ), the docs the name "GNU Mailman" but it then mentions it is technically the "Mailman Core" part and the rest is on separate docs, it took me for a while to get the hang of what it was exactly, Can we bundle this under one "GNU Mailman" and it contains 5 bundles "Suite", "Postorius", "Hyperkitty", "Core", "MailmanClient"? I think this reduces redundancy in the docs and makes them more comprehensible.
Or is the current approach more suitable for reasons that I would definitely like to learn and know. I would definitely like some pointers on this.
Technically the section "Testing mailman 3" of this page[2] will tell you how to run tests and you can see what the tests are under the "tests" folder of the specific repo, ( just see the .rst files ). In case of "facing several issues while setting up locally...", I believe asking in the this mailing list is the best option and if we recognize the problem to be common or something specific, we can write it under a section or at least in some sort of FAQs which are already present here[3]. For the problems which you feel in which "most of the developers felt difficulty," we can definitely look up the archives and make some FAQ out of those problems ( if the FAQ is not there already ), I am up for helping this if anyone of you GSoD folks picks it up.
[1] : https://mailman.readthedocs.io/en/latest/src/mailman/model/docs/model.html [2] : https://mailman.readthedocs.io/en/latest/src/mailman/docs/contribute.html [3] : https://wiki.list.org/DOC/Frequently%20Asked%20Questions
Cheers!
Hi Aaryan,
Thank you for your descriptive response.
Yes, I have gone through the "Models" section of the docs but it is more developer centric. I am suggesting that we should have docs explaining the use cases of all the features from both developer and user perspective.
I want to know if we can add this as a task as well. Also, it would be helpful to make the docs more detailed for Postorius and Hyperkitty as most of them are outdated. Also, it would be great if we can add the complete architecture of the project somewhere to give a overview of the project to the new developers who are interested in contributing.
I agree with this as it will reduce the effort , a new developer has to go through for the first time. It's very difficult for the maintainers and the mentors to reply to each and every thread on the mailing list and having a good documentation will certaily lessen the number of doubts being asked in the mailing groups.
Yes , now I am aware of it but personally, I faced these issues while setting it up on my local for the first time. I think creating a FAQ will be a good idea but again I am not sure the priority of this.
Also, I would like to know if I should post my proposal here so that the mentors can review it and give more insights on what is expected.
Thanks and Regards, Aditi ᐧ
On Sun, Jun 2, 2019 at 10:51 PM Aaryan Bhagat <aaryanbhagat377@gmail.com> wrote:
Hi Aditi,
Thanks for your interest on Mailman docs. I am posting some of my random thoughts and hope it helps :)
I have written a document on deploying to AWS using Docker < https://xiaoxing.us/2018/01/01/deploy-mailman-3-on-aws-using-docker/>, which I think is also applicable to local installation - just skip the SES configuration.
So, we can roughly categorize our users into three types: the Mailman Core, Hyperkitty and/or Postorius;
- Users of mailing list: They may not know what's Mailman Suite but using
- Maintainers of mailing list: They install mailman and they know what's that, but may not want to write a line of code;
- Developers of Mailman: They know much about programming and are willing (or forced) to write code on Mailman.
Think about it, as different type of user, what kind of document do you want? For example, as a normal user (Type 1), you will be happy if you see detailed description on how to operate the archiver, how to manage the subscription (though the web interface is quite friendly); and as a developer, you will need instruction on how to setup the dev environment and start working.
If you look at our Mailman GSoD page, there are two ideas: maintainer or a developer - but make it easy since maintainers may not know
- Instructions for Migrating from Mailman 2 to Mailman 3: That can be for a
how to code in Python.
- Developers' Documentation for Hyperkitty/Postorius: That's definitely for a developer, type 3.
And Aaryan has mentioned before, our documents on rtd are not that clear, and you may look back at this < https://mail.python.org/archives/list/mailman-developers@python.org/thread/W...> for Abhilash's words so you will
Actually, the Models section of the docs is not for developers of Mailman - it is for maintainers. If you want to create a tons of new lists, using cli is a good way. It may look like some very technical things though. When we are talking about "GNU Mailman", it is highly possible that it is about the whole project (including Mailman Core, Hyperkitty and so); and "Mailman" for "Mailman Core".
Personally, I think our docs need a reorder - you may think about it but it is going to be a big project.
And last, yes you are welcomed to post your proposal here so we can help review or give suggestions :)
Looking forward to your contributions.
Yours truly, Xiaoxing Ye http://www.linkedin.com/in/yexiaoxing
On Wed, Jun 5, 2019 at 11:52 PM ADITI GUPTA <aditi.medha96@gmail.com> wrote:
participants (3)
-
Aaryan Bhagat -
ADITI GUPTA -
Xiaoxing Ye