Proposing to re-invent our public-facing web assets

Looks good to me overall. In general I think that this is the right direction to move in for the diaspora project and this is what I think you’re asking to confirm from us at this point. All potential issues could be solved one way or another. So I find nothing blocking the proposal here.

I like the technical approach you chose. Static pages + minimal ruby backend for providing interactivity. Maybe that could even be turned into some kind of “documentation website framework” at some point in future.

I won’t repeat what others say, but I share some concerns stated above, like for instance what Hank said about search and indexing.

I don’t like the name “guides” for the FAQ/user help. It feels ambiguous to me. The fact that it combines information on different topics like podmin help, developer help and user help makes it hard to invent a good name for it. Podmin and developers will probably expect to find the relevant information under a name like “Documentation” while for user help expected name would be “User help” or “User manual” or “Usage hints” or “For diaspora users” or something. I don’t have a good solution here, but if we don’t have good names for the help section we could get the same problem as we have at the moment: people don’t understand where to look for the information they are interested in. This is probably just my impression though, so if nobody thinks it is an issue I’m okay with that. I just want to make sure that the required information can easily be found at the north star.

Appreciate the feedback.

Using Transifex instead of WTI; dropping the wiki, thus requiring a GitHub account to contribute; losing existing translations, …

I looked at more classical CMS like Wordpress, but also had a look at Drupal, TYPO3, MODX… Basically, in some cases, we simply couldn’t achieve everything we want, or managing the site would be so complex that we wouldn’t gain anything. Even more significant, using those systems would require some kind of backend account, and if you start looking at CMS with file-based backend so we could make the contribution process more streamlined… yeah, not so much. There is a non-zero chance I missed something, but I feel pretty comfortable claiming that building something tailored is likely the best idea.

Ah yeah, that was a fragment from me adding the edit button to the footer while being at a conference. I was aware of that issue, but didn’t find the time to address it. That now is fixed. However, there isn’t much translated content, but at least the “select language” selector will be German.

Everything is discoverable by search robots. Well, everything but the individual steps inside the installation guides, because the selector is based on JS, but the installation index page will be indexed, so that’s a non-issue. There is no hidden content unless we mess up, and even all the FAQs/Guides are listed in a simple list-of-links, for example here, which contains all guides, not just the top n, and this will also list all release announcements.

One thing that we need to do is to make sure to 301 redirect old URLs to the new site, which will make sure we don’t lose the search rank of our old website, but also will make sure people won’t get lost in old bookmarks.

The fun thing about that question is there is only one valid answer: I dunno.

Content itself should be pretty convertable, given it’s literally just a bunch of markdown files. With everything else, well, it depends on what the new site looks like. This is hard to plan, and so impossible to account for. In general, though, adding new subdomains for example should be simply done by adding a new section to the config. Other types of interactive contents could be build by adding a new module to site_modules and including it, … but that’s all things I can imagine right now. There probably will be another large-scale reinvention in 5 years from now, but that’s nothing bad.

I planned in adding a layout key to the frontmatter, just like jekyll did. In fact, there is even a views/layout directory, and MderbRenderer::mderb takes a layout parameter.

The thing is… I didn’t need it. I managed to build everything we have right now without the need for a second layout. So I didn’t implement it. If we ever need a second layout, we just need to add the layout key to the frontmatter, and implement a way to provide frontmatter defaults like jekyll does, and that’d be it.

Caches, in general, are evil. If you absolutely need them, they are still evil, but a necessary evil. But we don’t need them.

Everything is being rendered on demand, where “demand” is a http request. What this thing does in production is to load all files into redis, but only the files. I parse the frontmatter YML into a serialized object because parsing YML is surprisingly expensive (okay, it’s actually not surprising, but that’s off-topic), so this gets stored as a marshal’ed object, but the site’s contents are stored as unparsed mderb source. There are too many edge-cases we’d have to consider with caching.

As for salability… it doesn’t really matter. Startup times will get slower if we have lots of sites, but that’s only startup. Let’s just quote the redis docs for the command used to lookup pages here:

While the time complexity for this operation is O(N), the constant times are fairly low. For example, Redis running on an entry level laptop can scan a 1 million key database in 40 milliseconds.

We will not get to one million pages. Ever. Even with 100 translations, that would still be 10.000 pages. I don’t see that happening. Parsing markdown/erb has a cost, but I couldn’t reach the limits of that with doing a load test with ab on my macbook running a single puma thread, so… While response times won’t always be the amazing 4ms that it currently has (that is excluding reverse proxy and load-balancer roundtrips), it won’t be at the 40ms of the current site, or the super fast 310ms on average for a wiki page render.

To me, this is actually less about claiming to be a foundation (which, let’s be honest, nobody cares anyway), but more about readability and type-ability of that domain. diasporafoundation is actually really read to read and type for people with subpar English knowledge, and although we casually ignore that userbase most of the time, I’d like our official website not to do so.

Quite honestly, me neither. Here’s the thing, though: FAQ works in English, but that abbreviation is impossible to translate. Most projects stick with “FAQ”, but it turned out that that’s actually pretty horrible. The term is very well known within technical circles, but outside of that circle, most people are actually really confused. The traffic on the FAQ wiki pages is, compared to other pages, shockingly low.

With “guides”, I hoped to pick a term that’s both easily translatable, and more meaningful to users. Although it’s not super accurate, it makes clear that behind that link, there is content that explains how something is done. Besides that, it kinda forces us to write the contents in a different way. Instead of just answering hypothetical questions, it puts us into a position where we have to find topics to explain in a guide-like fashion. “How text formatting works”, “How can I discover contents?”, …

Does that change your opinion on that? If not, that’s probably a good sign we should reconsider that. :slight_smile:

* you people.

1 Like

Okay thanks for the clarification. I had a suggestion for the alternate route of contribution a la what uses (but that’s their primary) but I have a feeling with the edit-in-browser capabilities on GitHub that will be okay for +80% of contributors.

Understood. If you missed a fringe CMS I’d say it’s better to have something easy and clean like this with all of its features than go to some fringe one whose maintenance would be beholden to god knows who. So I think we are good.

That’s good! Would we tie into that for in-site searches? Good catch on the 301 as well! I ran into that with my own blog migration.

Again overall looks good to me. Even my question about what large collections and histories look like is going to be down to presentation layer changes which should be more than easy to do in this system so that’s an implementation detail not a go/no-go decision thing.

So @denschub you started this discussion with

Looking at the likes and comments here I think we can say that your project is well welcomed by everybody here. So you have the approval you were looking for :wink:

Honestly, nobody here had a veto, so I’m not even sure the next planned step “asking the world” is needed. This is our website after all :stuck_out_tongue: You can make this discussion public, but no need to call for a vote in my opinion. You did an amazing job, now let’s go ahead, fill it with content, polish the design and push to prod! :smiley: (There are more intermediate steps, obviously, but I’m getting excited :wink: )


I don’t know whether the name guides will produce normal level of traffic. I think we can try that and analyze the traffic level to see whether this works well for people or not. Let’s go with guides for now then.


Thanks for the feedback, @comradesenya!

Yeah, we generally don’t do votes here on Discourse. ;D But it’s still important that those discussions end up public, so just in case that someone has serious concerns, they have a chance to express those.

Everyone here has expressed their opinion, either in person, in this thread, or before you all knew about this idea in private conversations (like @goob), so I guess our private discussion is done here. Thanks, folks.

I’ll write the reply to post when the topic has been moved, then move the repo, make it public, and move this discussion in a public category.

Hello, World. Here’s a thing we have been working on.

Y’all will see that we’ve had some internal discussions before making this public, so I’d like to ask everyone who got interested after reading the title, to read the whole backstory here. It will also explain why this started of internally. :slight_smile:

The URLs shown above are still password protected, but the user credentials are provided as well. This is not done to lock people out, it’s mainly done to avoid search engines indexing the new pages by accident, which would be kinda bad. We (as in the community team and the core team) will also soon come up with a second post, explaining how content migration is going to happen. This plan needs some work, so please bear with us a little bit.

As you will probably see, the diaspora* core team, and our awesome community team, is on a consensus that we want to move forward with this plan. However, this is a community project, so we’d like to invite everyone to make some noise if you have serious concerns.



So let’s start 2 years ago when I created my pod… I managed to follow the instructions even for someone that I would qualify as a low level of linux knowledge. Then I also have the advantage that I know some linux gurus that helped me to correct all my mistakes, because the site was running but it wouldn’t have run for long if I only had myself working on it, that’s for sure. So the instructions are ok but not great.

Concerning the website I think the most important thing to me is the home page and the tutorial section for new users, even though I think the welcome email should contain an offline version of it that could be designed as a static page with the generator you’ve talked about. A possibility to add sections for sites that have optional features like Twitter integration or xmpp chat would be greatly appreciated.

For the new URL I agree that makes much more sense than the current URL.

Talking about /something that is so well hidden that nobody knows about it except the core team, I recently discovered the /public completely by accident, so all those possibilities should be clearly laid out for podmins and users so they’re much more aware of them.

To improve the appeal of the install guide I think showing that the project is up and running just fine would motivate people to invest the time and ressources to run a pod. Ideas I have would include a system where a podmin could have a specific country recommended to him where his pod would make the more sense, same thing for users, even if there is website but users don’t want to have to go through a list of hundreds of pods, they just want to use the service so improving that would go a long way towards improved user experience, just like a random chose your pod, so that not everyone joins the same.

I really love this project and will keep supporting it as much as I can, I’m glad to see things moving in other ways than just code improvement.


Coming in late here, but I think this looks very well-thought out. I have been active on the web since the 1990’s and started with open source projects in a big way in 2005, I think, so I’m very familiar with the DocsthatSuck syndrome. The organisation looks great too. May I just add,


This is where many great ideas fall short. No one checks them out for the viewpoint of someone actually needing them. You know what’s a great example? Anyone use YouTube events or Google Calendar? They’ve got millions and staff, yet they’ve obviously never tried to enter an event.

Enough, my comment is already too long.

I want to help. Where do I sign up?

1 Like

My rule for wine labels: short and memorable
My rule for product names: short and memorable
My rule for domain names… seems to say what the site is and is as short as possible.

1 Like

I like a lot about the new site. Especially the install guide. I am a Linux newbie and although I have some IT and engineering background the old guide was a bit… frightening. Also took me two tries to set up a pod. Looking back at it I can’t say it was bad or too inaccurate but on first read the impression was: “wow, this surely is tricky and can go wrong any time”.

About translations. I would like to contribute and help with Russian version. However the linked translation doc says:

If your desired language is not availble yet , please do not propose adding it on Transifex. Instead, open an issue on GitHub, so we can have a discussion about that.

…and currently translation project has just one language added. I suppose it is a bit too early to open Github issues about languages because surely existing translator teams will migrate to the new service?

1 Like

This is mixing diaspora*s UX and the project sites’s UX a bit here, isn’t it? However, there are a lot of contents on the project site that are hard to discover as well, so your point is still valid. In fact, one of the main motivations for building something new was the fact that some of the current contents are not as good as they could be, but improving them on the current codebase is kinda messy.

I am not too sure where you are heading at. To me, the comment sounds like you are more interested in contributing to diaspora itself, rather than the project site? If that’s the case, look in the #features-and-ideas category, there are a lot of discussions already. :slight_smile:

If you were talking about the project site, please hold off until we have some actual contents in there, because right now, it’s really just dummy content without any structure. As I mentioned previously, I can’t make exact statements on when that will be done, but this discussion will get an update, for sure. When we worked out our perspective of how the contents should look like, I would be more than happy to hear other opinions!

Good to hear that people are interested in that. Please note that, at this point in time, the only content that is polished even a tiny bit is the install guides, and even those need a lot of work; and they are not even translatable. :smiley: All the site’s contents are dummy contents at the moment, so translating anything at this point in time doesn’t make much sense. I will make sure there is a separate “Reaching out to site translators” post once the contents and the documentation for translating are finished!

Actually, no. While we could generate a list of eMail addresses from webtranslateit, signing them up on Transifex would violate multiple privacy laws, and be a kinda :poop: thing to do anyway. As mentioned, once the contents are in a state where translating makes sense, we will reach out to everyone and explain how the whole process looks like.

1 Like

I will help with anything I’m capable of, so both project and site. But my comment about usability is important and I think I can help there, yes, when there is something to look at. Having a bunch of peoiple who already know everything on a topic doesn’t really evaluate how understandable, attractive or memorable a site or text is.

I also would like to help with documentation, maybe by proofreading and giving my evaluation on it? Whatever works, I’m happy to give time to these things. Perhaps it would be wroth pinging me when there’s something like this to do because I don’t hang out much on Discourse.

1 Like


I only have a small note to the guide section: for first time it’s nice to have a hand-holding version, but the returning visits need the ability to actually pick the page I’m interested in without clicking through 46 steps. :slight_smile:

Good thing there is a “Show all instructions on a single page” link below the “install diaspora” button, which you can even bookmark.

Having multiple websites for one project is unacceptable and is just causing extra confusion. Information should be straightforwardly accessible and should obey common sense and intuition. I can help with refactoring this.

@denschub I have only now discovered the post about re-inveting the project site and visited the sites.
A absolut great idea to just start a new work and lets see if this is widely accepted - and it is!

I wish, I’ve found the redesigned installation sites earlier…

My 50ct to this:
To quickly translate larger amount of markdown paste it into Deepl translation machine - it makes readable translated texts and keeps formatting.
For a first shot to fill up the main languages it should be worth a try.

@denschub from the issues list of the project, which ones are blocker to see the new website published? All except the search feature I would guess?

All content issues, yeah, and that list probably isn’t complete. I just filed those issues to have some kind of tracking. Also check the pad-link I shared privately on March 4th.

I know I’m late to the party so please feel free to ignore, but I think “” or “” would be clearer. Just “” would also look very professional.