Proposing to re-invent our public-facing web assets

(Dennis Schubert) #1

Dear friends, it happened again. I wrote a long text I spent some time on a project-related idea and want your feedback on that now. The project is called north-star, and I really like that codename, so I had to share that with y’all.

Let me start with explaining why this is a team-internal proposal: if we decide to go ahead with it, it will contain some quite controversial implications, and it will have a major inpact on our public-facing communication. I worked on this project without the team’s “approval”, so I want to get your opinon first. If we all agree that this is a good idea, I plan on moving this proposal to a public category and ask the world if there are vetos. But I want this proposal to have the chance of getting rejected, if needed, without public outcry. :slight_smile:

What I am proposing ultimately boils down to…

  • Drop the current project site.
  • Drop the in-application FAQs/Guides.
  • Drop the current installation guides.
  • Drop the wiki.
  • Replace all of the above with something cooler.

Let me explain.

Motivation

I think we are a nice project, and we have some nice people, and even our main product is kinda nice! While we are doing a great job project-wise, I think we are doing a really bad job at doing “public relation”, documentation, and are generally bad at keeping folks informed. Let’s look at what we have right now:

The project website

Our current project website is not horrible, but kinda bad. I’ve heard from users, developers, podmins, and journalists alike that finding information is really hard. Even from people doing translations, I’ve heard multiple times that they translated a string and actually had no idea we had that information on the site, before they discovered it via webtranslateit. What is the target audience for our website? Users? Podmins? Journalists? Is the website and its contents really useful to anyone? I don’t think so, or at least I am having a hard time identifying who it’s for. That’s not good.

If we decide to go ahead and change all the contents, how would that look like? Currently, we would have to change the layout in ERB layouts, then hack multi-line content into the yaml file, then maintain the translations somewhere, … in addition, we have to maintain a database because we have some content in the DB, … it’s quite complex. Back in the day when I started working on the current site, I thought basing it on Ruby on Rails is a good idea, but these days… not so much. People who are doing lots of maintenance on the project site have told me multiple times that even getting the site running on their machine is a pain, and let’s not even talk about how complicated actual editing is. It’s not good.

The in-app help/FAQs

Soooo, we have /help. Hands up, who knew it was there? Well, I can’t see your hands now, but most of our users don’t! Sometimes, people are really surprised when I show them the help texts we ship with diaspora, they are really hard to discover.

Aaaand you guessed it, those texts are not very nicely written, and quite outdated. Also, what happens if someone wants to fix that? They’d have to get diaspora working on their machine, tackle the mix of ERB, a bit of Haml, Rails i18n, … just to fix some texts. That’s also not nice, and also really bad, as bad user documentation is one of the biggest issues we have that seperates us from a wider adoption by non-technical audiences. We also need to do much better here.

The wiki

When we installed the wiki, the main motivation was to enable more people to contribute to our documentation, assuming we eventually end up with super awesome docs on every topic imaginable. That… didn’t work out. Basically all active and current articles are maintained by core staff, or by very active community contributors, and the number of users and irregular contributors editing the wiki is not-actually-zero-but-still-zero.

These days, most of the edits are spam, and even though we enforce ReCaptcha for registrations, there is… a lot of spam. You can’t see it, as changes by new users are not visible, but have to be approved manually, but just to give you a number: on 25th December, there were 11 new users who immediately started spamming on their userpages. It’s bad.

The contents on the wiki are either well maintained articles by core members, or stale articles that have been started by someone years ago, but never received any love. However, most of the contents there are interesting, and should get more attention, but the wiki is maybe a less-than-ideal platform for that.

Also, on a technical base, the wiki is actually surprisingly painful to run. Not only does it require an Apache and a MySQL database (contrary to our project site, which is using nginx and postgres), it also needs a dedicated memcached to be even remotely performant, and it needs quite a lot of babysitting on a daily basis in terms of installing updates, fixing plugins, cache problems …

The installation guides

Those are also part of the wiki, but I wanted to split them off, as these are really important.

Before we had the wiki, we used GitHub wikis to maintain a single-page list of steps podmins have to follow if they want to set up a pod, but that guide was bad. When we had the wiki, we decided to move the install docs there, and some time after that, wonderful people spent amazing amounts of time to make them a bit more interactive, and allow people to select their operating system, their database engine, and make the guides easier to understand.

But still, those guides are not good. Podmins get confronted with a large wall of text, steps are sometimes confusing, the information is not really accurate, sometimes outdated… and, you can see a pattern by now, maintaining those is quite painful. By using variables in templates in macros, we achieved a surprising amount of flexibility, but it’s not what Mediawiki is supposed to do, and it’s not what it’s good at. Not good, and we really need to do better here.

The solution

Okay, I explained to you that our current state is not the best. The good thing is: for once, I have an actual solution! Not only do I have an idea, I actually spent some time developing that idea, into a fully blown proposal, including a live demonstration of code I wrote!

One thing this proposal includes is the deprecation (meaning: only exist as a redirect-hub for old URLs) of diasporafoundation.org. I want this project to use diaspora.software, as it is a much nicer domain. Besides the fact that we, technically, aren’t even a “foundation”, the domain is super long, hard to type, hard to read, and the word “foundation” doesn’t carry much meaning outside of some groups. “diaspora.software” is much more snappy: it’s about diaspora, it’s a piece of software, and besides the project name itself, there isn’t any ambiguity in how it’s spelled. Also, having the gTLD “software” makes it more explicit that we are, indeed, offering a software, and not a service that people can use.

Overall, I want us to have…

  • diaspora.software as the new project site
  • blog.diaspora.software as our blog
  • install.diaspora.software as the place to find install guides
  • guides.diaspora.software as the place users, podmins, and developers can find guides that help them getting their frequently asked questions resolved

The core idea™

I like static site generators like Jekyll. If you don’t know what that is: basically a piece of software that turns markdown files into HTML files. Simple webpages are usually a good case for that: you once define an HTML layout, and after that, all you have to do is publish markdown files. Quite nice, easy for editors to work with, easy to have checked in a Git repo, no database needed, no dedicated user-management needed, … it’s quite nice.

However, those don’t work for more complex sites. As soon as you require some kind of interactivity, like handling user input, static site generators don’t work. So, building the project site, and especially the install guides, on something like Jekyll, is really hard. And with requirements like internationalization, it turns into an almost-impossible problem.

But… maintaining contents as markdown files would still be amazing. Imagine if we could just all work on GitHub, send Pull Requests changing markdown files that can be viewed and edited right on GitHub itself, …

I built something.

I deployed that something onto our server, but I put it on some example subdomains and also added password protection, mainly to prevent Google from indexing it. Whenever I link something, you can use username northstar and password kitten to get access. I also pushed the code to GitHub, and you are all added. It’s a private repo, mainly for the same reasons as this proposal being private. But it should give you an idea, I hope. :slight_smile: The source code can be accessed at https://github.com/diaspora/north-star

Content editing

Well, it’s markdown. Mostly, that is. I mixed plain markdown documents with some ERB, to allow for more… flexible documents. Imagine the install guides, for example: those would be not very useful as static markdown documents, because we need to inject distribution-specific variables like the package list. The server takes those files, renders them, and serves them to the browser. So we kinda have a static file generator, without there being a static file generator. Check this document for more architectural notes.

Easier contributing

The only dependency of that project, in development, is Ruby. Once you have installed Ruby, you are good to go. No database server needed, which makes local setup for contributing and testing changes much easier.

Actual live demos!

Okay, I teased you a bit, but there you go. Note that this is a technical demo, not a demo of well-written contents. It’s mostly dummy contents, really. I’ll make a proposal for how we can get nicer contents as soon as we decided that this is a good idea. (Yes, I have plans for that.)

The project site

diaspora.software

As you can see, it kinda looks like our current site. These are the source files for the contents, should give you an idea of why I think that markdown files are a good idea. Just for reference, this is the code behind the current index page.

Also,

blog.diaspora.software

That’s still mostly the same. As you can see, I decided to split the blog content up into release announcements, and other stuff. I want us to post more content to the blog, posts like the “where is my feature” masterpiece, for example, shoudl absolutely be on our blog as well. Each blog post, again, is its own file.

The guides (formally known as FAQ)

guides.diaspora.software

These are just like our current in-app help, and the FAQ in the wiki. They are split into sections for users, podmins, and developers, where the user section gets the most visibility. The guides are individual markdown files, can be grouped into subcategories… you get the idea when looking at that site.

Install guides

Noooow, the really cool thing.

install.diaspora.software

Just have a look at that! I attempted to guide podmins through the process, instead of dumping all the contents. You start off by selecting your target environment, and then enter a multi-step guide that shows you what you have to do. And even though I just copy-pasted the texts from the wiki, it’s already much nicer. Imagine how that would look like if we spent some time polishing the texts…! :wink:

The install guides are a great example to show off another neat thing: data files. Have a look at the data file for the installation guides, and most of the time, that’s all you need to touch when adding new distribution versions, fixing something, … Overall, I think this reduces our maintenance effort by a fair bit.

The bad things

So, as you can see, I am quite hyped, and I know other folks are as well. I think it would be a huge improvement to our current state, but as usual, there are downsides as well.

Handling translations

Currently, our project handles translations on WebTranslateIt. There are some limitations with WTI, but one of them is the way WTI handles strings. While you can upload multiple files, it ends up collecting all strings and listing them in an alphabetical list. That works fine if you translate software projects like diaspora, but it falls apart when translating content pages where you have multiple strings on one page, and where context is important.

In my proposal, I wrote automation for Transifex. Transifex is a different service, but a much more commercial one. They support opensource projects, but it’s … a different feel. The largest benefit is how Transifex handles multiple files. Each file is displayed on its own, where the translations are in context, and in the order they appear in the file. That way, all translations are in context. Have a look at this documentation, where I explained the details.

I like Transifex, but it would be another service. And it requires a Transifex account.

The code is still home-brew

I looked at already existing CMS, but none of them really fit our needs of simple content management and flexible layouts, while at the same time being accessible to contributors, and having a content history.

The code is based on Sinatra, but there are 650’ish lines of Ruby that I wrote myself. Most of the code should be easy to understand and maintainable, but it’s still no off-the-shelf solution.

Contributing to the site requires a GitHub account

In reality, I don’t think this is a problem, but while previously, you could contribute to the wiki by creating an account there, you would have to have a GitHub account after this proposal. However, that’s also a benefit, since we would get the whole review-workflow for free. And GitHub’s spam protection.

Outro

So, that’s my proposal. Please let me know what you think. Please think about it, and if you have any concern, questions, or just something you want to say, please do so. I want this to be a well-planned, and well-thought step. If there is anything we can improve (architecture wise, obviously, the contents need lots of work), we should do so. If you’re into Ruby, check out the GitHub repo (especially the _server subdirectory), and let me know if you have any feedback.

There are also a lot more details I want to talk about, but this text is already waaaay too long. SO I hope you understand everything, and can form your opinion. If not, let me know.

Thanks. Merry Christmas.

8 Likes

Getting involved
Diaspora is a Secret - Ideas for "onboarding"
(Flaburgan) #2

Thank you very much for your hard work and that nice proposition @denschub! I really like it.

I’m happy to see that the user experience is going improved, I agree we don’t give enough weight to that. What you came up with for the installation guide is already 100x better than the current wiki. I can’t wait to work on the new site design / texts (spoiler, my girlfriend is leaving for 6 months because of a new job so I should have more free time until June).

Your technical choices look fine, to go from several databases (including the wiki one) to 0 to maintain is easier for sure. Needing to create pull requests instead of a wiki edition is maybe harder for new contributor, or maybe not (as github allows to edit file without pulling the repo and we’re talking about markdown files only). However it will add a review step so we need to be careful to not delay contributions too much there (but maybe that’s the opportunity to give some not-very-involved-at-the-moment-contributors write access to encourage them to contribute more).

Small point about the in-app /help: it has the benefit to be linked to the version the pod is using. So if a pod isn’t updated, the help still matches the software, which is not the case of the official website which will always follow the last diaspora* version. I don’t know if that point is important enough to keep the in-app help or not, but I wanted to point it.

To sum it all: thank you very much, and let’s go to another big step for the project!

1 Like

(Waithamai) #3

Optional features like chat could also cause problems. Maybe there’s a way of making clear which features are optional, and which features and help texts have been added/changed since the last major version. There’s no need to point out rewording, but sometimes the entire content of a section might change and users should be aware of this.

0 Likes

(Dennis Schubert) #4

Yeah, good idea. For issues where it matters, we can simply use the infobox template (like the blue/yellow boxes in the install guides, or the warning template in the wiki) to point that out.

You two are right, though, there are a few potential fallacies when shipping a centralized help, but at the same time, it also is a good thing. If we miss a documentation update for in-app stuff, we have released the version and our opportunity is gone. If we have the documentation centralized, we can update the docs whenever we feel like. Having the docs centralized also makes maintenance for community members easier.

All podmins should update fast anyway, so in my opinion, that’s a tradeoff that works for me personally. But it’s good to keep in mind, maybe we have to revert that decision eventually!

0 Likes

(Hank G) #5

TL;DR of my long post: Overall thumbs up on this idea.

I spent a bunch of time reading over this discussion, looking at the source code, playing with it, writing some example new posts, etc. My off the cuff reactions are all positive with some follow-up questions that I couldn’t determine the direct answers to.

First, Yes absolutely I agree we need a redesign of these things for the exact reasons you’ve stated. There is a wealth of information in there but it’s amazing how hard it is to find sometimes. It was less than a year ago when I started working on the project and the Wiki install guides etc were pretty good for the core install but finding solutions to questions and some other things can be hard. I have bookmarks for some things that I know I spent a bunch of time searching for and could only find by looking at browser history, etc. So kudos for the team addressing that.

Beyond that I had no idea how hard the management of the sites was both from a structural/updating process point of view and a dealing with spam and other content point of view. What you have described is definitely completely unworkable. It’s amazing you guys haven’t done something like this up until this point by dropping to Jekyll or some CMS style system. You hit the nail on the head on limitations of Jekyll (can’t speak to others) and dynamic content. I just got done fighting that with my own blog and getting the Vue code working inside a Jekyll site for that whole “blog discussion timeline” proof of concept usage of the API. That one went so far as only working by embedding in an IFRAME because the Markdown processor was eating my Vue variables alive lol.

In the original post it was stated that some of this may be controversial. I’m not sure what that would be referring to. The only thing potentially controversial about your proposal from my perspective is using a custom system versus an existing one. My first question whenever a suggestion like that is brought up on a project is whether a survey was done of existing technologies. You answered that it has and you’ve identified some really interesting cases for translations and dynamic content we will encounter from the get go that CMS’s don’t/can’t handle. I can definitely see the advantage of your approach and there are some really solid things about it:

  • Love editing via Markdown files
  • Love managing from Git and pull requests. For people who aren’t comfortable with that path we could have an alternative contributions process similar to what opensource.org uses.
  • Dynamic content is very powerful for pages that need that (like the install) and seems to be a clean implementation.
  • Much of the content is straight markdown so it “just works” in other platform if ever it was decided to switch years from now. I imported the non-dynamic posts into a Jekyll site and it went in pretty cleanly and my Jekyll blog posts dropped into this site cleanly too. Beyond data portability for static content it also means contributors who are putting up blog posts, simple documents that would only have translation services etc, can edit that in a very familiar way.
  • The site translations management system looks interesting but it’s not working on the present version (self-served throws no method error and the hosted one has internal server error) but get the concept form the config files and looks really nice.

Some questions that came up during my review that I couldn’t figure out from just looking at it and/or I thought were worth discussing. I got down in the weeds on some of them which may be too early to worry about. If any fall into that category just say “let’s discuss that later” or something.

  • How do we envision search and larger lists/indexes/etc working with this system? Is the way the site is generated such that DDG or another system can index it properly and give us it “automagically” or is there something else we would need to look into to achieve that? Do we have a page we could populate with examples beyond the landing pages were the lists would have dozens or hundreds of items not just a handful? These would be especially necessary for guides, blog posts, FAQs, etc.
  • Do we have any support concerns with a home grown approach? The code is pretty standard Ruby and a relatively small code base so it’s pretty straight forward to people familiar with it, which includes Diaspora developers. I felt pretty familiar with it right away when playing around with it tonight. However are there things we should be thinking about that may get in the way later though? Like what would a total reorganization of the site look like if that was done a few years from now? Is it mostly changing configuration files and tweaking code or the other way around?
  • How is site layout design handled? For example if there is a page that needs a slightly different styling where is that change made? I see the views/components and views/layouts folders. Is this similar to the _includes and _layouts in Jekyll, respectively? Is cueing off a layout keyword or something what is envisioned?
  • What is the pipeline for purely static pages? Are they being rendered and cached on start up or the first time they are accessed and then that is simply rehosted or is it being regenerated on each request? Do we have any scalability concerns related to any of that? Considering people on this forum say it feels much faster I’m assuming the answer is “no” even if there were thousands of articles but I figure it couldn’t hurt to ask.

Overall I’m stoked about what you’ve come up with and addressing the problem with this sort of an approach. According to the commit log you’ve spent 2+ months working on it and thinking about it (probably even longer thinking about it) and that definitely comes across. For some of the questions above (search, site navigation, etc) it may make sense for us to populate this with some stand-in content that looks like years of content to see how the experience feels from all perspectives (readers, creators, designers, administrators, maintainers) and tweak as necessary. I think it feels great from a landing pages perspective in each of the sections and “top view” lists but I can’t get a feel for how I’d find something more buried by time or obscurity, which is a problem we are trying to tackle with this redesign.

0 Likes

(goob) #6

Sorry I haven’t managed to engage properly with this proposal yet. For now, I’ll just say that based on earlier conversations with Dennis, this gets a big thumbs-up from me.

1 Like

(Flaburgan) #7

One potentially controversial change would be (in my opinion) the switch of the domain. Indeed, we don’t exactly have a foundation structure we’re managing, so diaspora.software better reflects the reality. But “foundation” brings trust, and we probably need that. As we are trustworthy, I don’t feel like a liar when using the diasporafoundation.org domain. That’s the only controversial change I can think of from my point of view.

1 Like

(Comrade Senya) #8

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.

0 Likes

(Dennis Schubert) #9

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

(Hank G) #10

Okay thanks for the clarification. I had a suggestion for the alternate route of contribution a la what opensource.org 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.

0 Likes

(Flaburgan) #11

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: )

3 Likes

(Comrade Senya) #12

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.

2 Likes

(Dennis Schubert) #13

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.

0 Likes

(Dennis Schubert) #14

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.

Thanks!

3 Likes

#15

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 diaspora.software 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 podupti.me 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.

2 Likes

(It Was Me) #16

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,

USABILITY TESTING

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

(It Was Me) #17

My rule for wine labels: short and memorable
My rule for product names: short and memorable
My rule for domain names…

diaspora.software seems to say what the site is and is as short as possible.

1 Like

(Spc Cw) #18

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

(Dennis Schubert) #19

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

(It Was Me) #20

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