Abhilash did a lovely job on the new website, but while the layout has changed, a lot of the content hasn't. And I'm not sure what we've got lines up very with what people want out of our website, so I'm thinking about re-organizing.
Right now, I suspect that when people visit list.org, these are the things they want to do:
- Find out what mailman is.
We're good at that right now: there's good info on the main page and then links to features.
- Find out how to get and install the latest version of Mailman.
Need improvement here. Mailman 2.1 download links are good. Mailman 3 directs you to PyPI but then there's nothing explaining about how Mailman now is a suite and it's this bunch of packages. Also nothing about how you can use mailman-bundler rather than trying to make the magic happen yourself.
I wrote something up and put in a merge request, pending someone proofreading it: https://gitlab.com/mailman/mailman-website/merge_requests/5
- Find out how to report a bug
We kind of fail on this one, except if you want to report a security issue. Again, this is more complex than it might seem since there's a bunch of different components.
- Find the docs / get help with an issue.
The good: they're linked right there in the top bar. The bad: is someone looking at this going to know they want the docs for postorius vs hyperkitty? Will any of that make sense? I think we might need a landing page here.
We do have a "help" link and the "wiki" link in this area too, but I think a landing page could bring this all together more nicely.
- Find out how to contribute.
This is going to be especially gsoc students. We've got some nice developer links and yeay, this is one of the pages that lists out all the parts of Mailman! But we could really use a startup guide here.
We do have a nice Donate link for financial contributions, though.
- Figure out how to get in touch with us.
This page is pretty decent, with the mailing lists and IRC and all. Maybe if we had a "how to report a bug" page it should be linked here, but otherwise full marks.
- Learn more about Mailman
We've got some good resources: features, media, the code of conduct, etc. But probably we should group this all together so that it's easier for people to find the other important things they want without wading through all these links.
I'd suggest we keep the top of page links as they are, since they're super useful to people who know what they're looking for already, and have the left side menu be more about the guides.
But I think we should replace all the links down the left-hand side of the page with links that match up with those goals, so the menu would probably look something like:
- About Mailman
- combine all the about mailman stuff here, although we also want to leave the main page as is, so there may be a bit of duplication here.
- Get Mailman
- Links to source code and install guides, high level description of what to do.
- Help and Documentation
- landing page with a link to the docs, wiki and mailing lists, with instructions. Maybe some search boxes? Userguides go here too.
- Report an issue / Contact Us
- landing page with reminder about reporting security bugs, links to bug trackers, mailing lists, irc
- How to Contribute
- new contributors guide here, prefaced by the basic source/gitlab links
Thoughts on better ways to set this up? Other suggestions of things people often want out of our website?
Terri
On Sat, Dec 05, 2015 at 01:10:10AM -0800, Terri Oda wrote:
- Find out how to report a bug
We kind of fail on this one, except if you want to report a security issue. Again, this is more complex than it might seem since there's a bunch of different components.
Would it be easier here, to list the components, and then maybe link to the docs, and roadmap/issue tracker?
something better presented than:
| mailman 2 | stable version | docs | bug tracker | mm-users | | mailman bundler | everything | docs | bug tracker | mm-devs | | posterious | | hyperkitty |
or maybe a page linking to each item? Something like https://www.mysociety.org/projects/components/ (usual disclosure: I'm a co-founder of mySociety).
- Find the docs / get help with an issue.
The good: they're linked right there in the top bar. The bad: is someone looking at this going to know they want the docs for postorius vs hyperkitty? Will any of that make sense? I think we might need a landing page here.
Maybe clarified in the above layout suggestion?
- Get Mailman
- Links to source code and install guides, high level description of what to do.
Possibly also things like packages.debian.org/mailman etc; homebrew; I would expect that most people will install with their package manager, despite what 'we' might prefer.
- Help and Documentation
- landing page with a link to the docs, wiki and mailing lists, with instructions. Maybe some search boxes? Userguides go here too.
- Report an issue / Contact Us
- landing page with reminder about reporting security bugs, links to bug trackers, mailing lists, irc
Link to the hot topics (dmarc, install, what ever's currently getting the most hits in a given period)?
- How to Contribute
- new contributors guide here, prefaced by the basic source/gitlab links
Avoid duplication here, maybe, and just link to the Sphinx/RTD pages? Fairly sure I've seen a CONTRIBUTE file, somewhere. Maybe also link to coding standards (I think these are unified for the various components).
Thoughts on better ways to set this up? Other suggestions of things people often want out of our website?
Do ordinary folk want to find "where can i get one of these set-up for me" -- the vendors/hosting list, perhaps -- although maybe with some sort of ratings thing (and a last updated / which versions).
-- "You can't say that, because it's true." (unnamed Russian censor, to Malcom Muggeridge, 1933)
On 2015-12-05 10:21 AM, Adam McGreggor wrote:
On Sat, Dec 05, 2015 at 01:10:10AM -0800, Terri Oda wrote:
- Find out how to report a bug We kind of fail on this one, except if you want to report a security issue. Again, this is more complex than it might seem since there's a bunch of different components. Would it be easier here, to list the components, and then maybe link to the docs, and roadmap/issue tracker?
something better presented than:
| mailman 2 | stable version | docs | bug tracker | mm-users | | mailman bundler | everything | docs | bug tracker | mm-devs | | posterious | | hyperkitty |
or maybe a page linking to each item? Something like https://www.mysociety.org/projects/components/ (usual disclosure: I'm a co-founder of mySociety).
Yeah, my biggest concern with the table approach is actually that people won't know what component they're using when they want to report a bug. I think we can probably do something more like the latter and then suggest that people submit against suite or maybe core if they're not sure and we'll move bugs as needed.
How does moving bugs work in gitlab? I haven't had to do it yet.
Actually, the "what component am I using?" is a problem in a few places. Maybe something more extensive on the front page explaining the projects and then on all the other pages we can say things like "HyperKitty web archiver" and link to the docs for more explanation.
- Find the docs / get help with an issue.
The good: they're linked right there in the top bar. The bad: is someone looking at this going to know they want the docs for postorius vs hyperkitty? Will any of that make sense? I think we might need a landing page here.
Maybe clarified in the above layout suggestion?
Indeed.
- Get Mailman
- Links to source code and install guides, high level description of what to do.
Possibly also things like packages.debian.org/mailman etc; homebrew; I would expect that most people will install with their package manager, despite what 'we' might prefer.
We've never bothered to link all the various packages for various distros before, but I do think we might need some explanation here if it turns out there's a lot of different names for the suite packages. I know we have some rpms, but does anyone have those actually in a distro yet that we could point at? In my experience, pointing at packages not in distro upstream isn't any better for many admins than PyPI is.
- Help and Documentation Link to the hot topics (dmarc, install, what ever's currently getting the most hits in a given period)?
Ooh, good idea. Wonder if we can automate this from wiki hits? Probably fine to just choose a couple manually, though; they don't tend to change that rapidly.
- How to Contribute
- new contributors guide here, prefaced by the basic source/gitlab links
Avoid duplication here, maybe, and just link to the Sphinx/RTD pages? Fairly sure I've seen a CONTRIBUTE file, somewhere. Maybe also link to coding standards (I think these are unified for the various components).
We do somewhere have a CONTRIBUTE file, but if I recall correctly, it's clear to experienced open source contributors but not so useful to folk for whom mailman is their first project who'll need more extensive links to resources and answers to common questions. Since we get a lot of GSoC student aspirants and folk who meet one of us and think "these seem like nice people, maybe I'll make my first open source contribution with them," I think there's good reason to have something a bit more extensive than the existing CONTRIBUTE stuff.
That said, this new-contributors document might be just as well placed in the wiki so all community members can update it more easily.
Thoughts on better ways to set this up? Other suggestions of things people often want out of our website?
Do ordinary folk want to find "where can i get one of these set-up for me" -- the vendors/hosting list, perhaps -- although maybe with some sort of ratings thing (and a last updated / which versions).
Yes! We have a page on the wiki for hosting services to add themselves and we should link it. I don't think we have resources to maintain ratings or version info, but if you're interested in doing that, I think people would find it useful. I assume this should be linked in the "Get Mailman" section?
Terri
On Sat, Dec 05, 2015 at 01:28:55PM -0800, Terri Oda wrote:
On 2015-12-05 10:21 AM, Adam McGreggor wrote:
On Sat, Dec 05, 2015 at 01:10:10AM -0800, Terri Oda wrote:
How does moving bugs work in gitlab? I haven't had to do it yet.
Or even linking to issues raised in other repos…?
Actually, the "what component am I using?" is a problem in a few places. Maybe something more extensive on the front page explaining the projects and then on all the other pages we can say things like "HyperKitty web archiver" and link to the docs for more explanation.
I've grown rather partial to foo-meta repos, purely for bug reports, design spec, common docs for whole projects with multiple components; admitedly, I'm more used to using GitHub and linking to issues raised in meta in components (but meh, FSF dogma/policy…)
- Get Mailman
- Links to source code and install guides, high level description of what to do.
Possibly also things like packages.debian.org/mailman etc; homebrew; I would expect that most people will install with their package manager, despite what 'we' might prefer.
We've never bothered to link all the various packages for various distros before, but I do think we might need some explanation here if it turns out there's a lot of different names for the suite packages.
There is that, too, yes…
I know we have some rpms, but does anyone have those actually in a distro yet that we could point at? In my experience, pointing at packages not in distro upstream isn't any better for many admins than PyPI is.
~My~ preference for installing stuff is: - disto repos (incl. backports) - semi-official repos (e.g. ppas, vendor's repos) - cpan/pypi/gems - build from source
Others might throw in things like Docker at the top, but I'm unimpressed with Docker.
- Help and Documentation Link to the hot topics (dmarc, install, what ever's currently getting the most hits in a given period)?
Ooh, good idea. Wonder if we can automate this from wiki hits?
Or indeed, the analytics (which I'm guessing we have, but CBA'd checking).
Probably fine to just choose a couple manually, though; they don't tend to change that rapidly.
Larry's Laziness, Impatience, Hubris springs to mind here…
- How to Contribute
- new contributors guide here, prefaced by the basic source/gitlab links
Avoid duplication here, maybe, and just link to the Sphinx/RTD pages? Fairly sure I've seen a CONTRIBUTE file, somewhere. Maybe also link to coding standards (I think these are unified for the various components).
We do somewhere have a CONTRIBUTE file, but if I recall correctly, it's clear to experienced open source contributors but not so useful to folk for whom mailman is their first project who'll need more extensive links to resources and answers to common questions.
Ah yes, My First Open Source Project…
Since we get a lot of GSoC student aspirants and folk who meet one of us and think "these seem like nice people, maybe I'll make my first open source contribution with them," I think there's good reason to have something a bit more extensive than the existing CONTRIBUTE stuff.
I imagine there's content that's available already, too, for My First Project, for some reason, I'm thinking it's the sort of thing Mozilla will have done a fair few iterations on (and will be nicely licensed).
That said, this new-contributors document might be just as well placed in the wiki so all community members can update it more easily.
Maybe it's just me, but the Wiki doesn't look that user-friendly as it currently stands.
Thoughts on better ways to set this up? Other suggestions of things people often want out of our website?
Do ordinary folk want to find "where can i get one of these set-up for me" -- the vendors/hosting list, perhaps -- although maybe with some sort of ratings thing (and a last updated / which versions).
Yes! We have a page on the wiki for hosting services to add themselves and we should link it. I don't think we have resources to maintain ratings or version info, but if you're interested in doing that, I think people would find it useful. I assume this should be linked in the "Get Mailman" section?
It'd be useful to run a linkchecker, at least…
On 2015-12-05 5:44 PM, Adam McGreggor wrote:
Since we get a lot of GSoC student aspirants and folk who meet one of us and think "these seem like nice people, maybe I'll make my first open source contribution with them," I think there's good reason to have something a bit more extensive than the existing CONTRIBUTE stuff.
I imagine there's content that's available already, too, for My First Project, for some reason, I'm thinking it's the sort of thing Mozilla will have done a fair few iterations on (and will be nicely licensed).
Yes, such content exists, and we can link to some of it, but it's typically too general for a beginner who doesn't yet know how to handle that. I spend literally hundreds of hours a year talking to students about where they get stuck as new contributors as part of my role as the Python GSoC coordinator, plus I hang out in the OpenHatch channel (they're one of many orgs that works to make the "how do i get started?" docs better) and I hear the "I got this far but then there were no architecture docs and I got overwhelmed" and variants on it a lot.
We need those architecture docs and that bridging stuff that goes from "how to github" to "what does mailman want in a pull request and how many tests do I need to include if I want to make Barry happy?"
It's a moot point to argue about it, anyhow. Either I write this now for the website or I write it 40 times on IRC in February while the students complain that I'm not answering them fast enough, and I know which one I'd prefer! ;)
Terri
On Dec 05, 2015, at 01:10 AM, Terri Oda wrote:
Abhilash did a lovely job on the new website, but while the layout has changed, a lot of the content hasn't. And I'm not sure what we've got lines up very with what people want out of our website, so I'm thinking about re-organizing.
Big +1.
- Find out how to get and install the latest version of Mailman.
Need improvement here. Mailman 2.1 download links are good. Mailman 3 directs you to PyPI but then there's nothing explaining about how Mailman now is a suite and it's this bunch of packages. Also nothing about how you can use mailman-bundler rather than trying to make the magic happen yourself.
We have something of a landing page, minimal as it is:
http://docs.mailman3.org/en/latest/
and its git repo:
https://gitlab.com/mailman/mailman-suite-doc
Certainly the content could be expanded on and improved, but I'm not sure whether it makes sense to exit from the website to this readthedocs page or pull the content into the website. We probably don't need it in multiple locations.
- Find out how to report a bug
We kind of fail on this one, except if you want to report a security issue. Again, this is more complex than it might seem since there's a bunch of different components.
Probably not the most discoverable, or readable though.
- Find the docs / get help with an issue.
The good: they're linked right there in the top bar. The bad: is someone looking at this going to know they want the docs for postorius vs hyperkitty? Will any of that make sense? I think we might need a landing page here.
I sense a theme. :)
- Find out how to contribute.
This is going to be especially gsoc students. We've got some nice developer links and yeay, this is one of the pages that lists out all the parts of Mailman! But we could really use a startup guide here.
For sure.
- Learn more about Mailman
We've got some good resources: features, media, the code of conduct, etc. But probably we should group this all together so that it's easier for people to find the other important things they want without wading through all these links.
I'd suggest we keep the top of page links as they are, since they're super useful to people who know what they're looking for already, and have the left side menu be more about the guides.
But I think we should replace all the links down the left-hand side of the page with links that match up with those goals, so the menu would probably look something like:
- About Mailman
- combine all the about mailman stuff here, although we also want to leave the main page as is, so there may be a bit of duplication here.
- Get Mailman
- Links to source code and install guides, high level description of what to do.
- Help and Documentation
- landing page with a link to the docs, wiki and mailing lists, with instructions. Maybe some search boxes? Userguides go here too.
- Report an issue / Contact Us
- landing page with reminder about reporting security bugs, links to bug trackers, mailing lists, irc
- How to Contribute
- new contributors guide here, prefaced by the basic source/gitlab links
Thoughts on better ways to set this up? Other suggestions of things people often want out of our website?
A lot of that makes sense Terri, and thanks for thinking about this.
High level bits seem to me that we need a richer landing page for Mailman 3 that brings all the resources for that version together, and better left hand menus.
Cheers, -Barry
On Mon, Dec 7, 2015 at 4:47 PM, Barry Warsaw <barry@list.org> wrote:
On Dec 05, 2015, at 01:10 AM, Terri Oda wrote:
Abhilash did a lovely job on the new website
+1
- Find out how to get and install the latest version of Mailman. ... We have something of a landing page, minimal as it is:
In my opinion, that link should replace ALL other links under the Documentation menu at the top of the home page (www.list.org), and it should clearly specify MM 3, something like:
Documentation
Mailman 3 => http://docs.mailman3.org/en/latest/I am ready (finally) to start new lists with MM 3 and that, I assume, is where I should look.
Thanks.
Best regards,
-Tom
participants (4)
-
Adam McGreggor -
Barry Warsaw -
Terri Oda -
Tom Browder