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: - Users of mailing list: They may not know what's Mailman Suite but using the Mailman Core, Hyperkitty and/or Postorius; - 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: - Instructions for Migrating from Mailman 2 to Mailman 3: That can be for a maintainer or a developer - but make it easy since maintainers may not know 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/W34D5MBJ3HLYKE2DY3B6KOXMILKE4CPN/> for Abhilash's words so you will > So, Mailman Suite is the entire collection of projects mentioned above and "http://docs.mailman3.org/en/latest/"; is supposed to be the Landing page for documentation needs. > It points to documentation for sub-projects and if there are missing pieces, we welcome fixes/changes to that page. Change could be to make discovery easier, or to make format better, aside from the actual text. 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.medh...@gmail.com> wrote: > Hi Aaryan, > > Thank you for your descriptive response. > > >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. > > 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. > > >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. > > 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. > > >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. > > 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. > > >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 ). > > 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 <aaryanbhagat...@gmail.com> > wrote: > > > Hello Aditi!, > > I am a fellow contributor in this organization under GSoC programme. > Great > > to have you onboard with us. > > > > >1) 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. > > > > 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. > > > > > > > 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. > > > > 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! > > _______________________________________________ > > Mailman-Developers mailing list -- mailman-developers@python.org > > To unsubscribe send an email to mailman-developers-le...@python.org > > https://mail.python.org/mailman3/lists/mailman-developers.python.org/ > > Mailman FAQ: https://wiki.list.org/x/AgA3 > > > > Security Policy: https://wiki.list.org/x/QIA9 > > > _______________________________________________ > Mailman-Developers mailing list -- mailman-developers@python.org > To unsubscribe send an email to mailman-developers-le...@python.org > https://mail.python.org/mailman3/lists/mailman-developers.python.org/ > Mailman FAQ: https://wiki.list.org/x/AgA3 > > Security Policy: https://wiki.list.org/x/QIA9 > _______________________________________________ Mailman-Developers mailing list -- mailman-developers@python.org To unsubscribe send an email to mailman-developers-le...@python.org https://mail.python.org/mailman3/lists/mailman-developers.python.org/ Mailman FAQ: https://wiki.list.org/x/AgA3 Security Policy: https://wiki.list.org/x/QIA9
