How to integrate documentation

I think documentation about how the platform works and information on hospitality exchange in general are also content that attract new and probably the right kind of users from the outset.

When I look at other hospex sites, I feel this easily ends up scattered in different places and sections over time and then puts effort on the reader to put the whole picture together. I also feel it’s lacking a bit of creativity when just being presented as FAQs.

So I thought it could be helpful to collect ideas on how to approach, organize and present this part of the platform. :slight_smile:

Personally I would love to see a trust architecture similar to discourse implemented on the site, because I think its levels and achievements/badges can be designed creatively and clearly laid out in the documentation. I also like how on discourse these are referenced from different parts of the site, without the user ending up in an arcane place.

I would also favour a more literary introduction instead of just faqs. Probably a handbook/booklet that could be downloaded as well? I still love the “Valve Handbook for new employees”, to share an example:

1 Like

I think this is a great idea.

I think it’s important to have a clear explanation of what the point of is to those who haven’t stumbled across it elsewhere. The problem might be that it’s a very different thing for different people :P.

Yes! Though in this context I wouldn’t think of it as the problem, but the essential quality to appreciate and build on! :hugs:

1 Like

My ideas:

  • Introduction: In the process of registration, the new user could have to watch a short explanatory video about values and ethics of hospex in general and in particular
  • Documentation: A handbook as proposed by @nolo is a good idea, but it should be in html, not pdf. Then, for example, the “how to send a good request”-section of the handbook could be set as a link next to the request text field.

A short video might be nice if you include people from different cultures to explain that in each culture some things are perceived differently. Will also show new members that doing some research into local costums might be a good way to start a trip.
Also some basic general rules everybody has to stick to, like no sex-requests, being polite in posts/forum, always have a back-up plan (just in case you don’t find a couch), once you have country pages a small wiki like on public transport, currency, food, drinks, rules, laws, … that might be important for couchers.
I did help create a video called “One Couch at a time” about the spirit behind Couchsurfing and other time/space sharing websites. Sharing food, time, spaces, idea’s, … and what it might mean for you and your hosts.


I actually really like this idea. This could be a good way to make sure people making accounts are engaging with us consciously and purposefully from the get-go. Forcing new users to watch a video as part of the sign-up could, of course, deter people from completing the sign-up, but those people might be the ones we want deterred anyway… :thinking:

1 Like

Continuing the discussion from Running/attending a regular meetup:

I love this idea! I had suggested handbook as a a general introduction to the platform and I generally think it would be so much nicer to have some handbooks, instead of faqs or a wiki. I think we’d also have the community that would love to contribute and collectively write some handbooks!?

Who else loves handbooks? :partying_face: :sunny:

1 Like

Handbooks can be great, but they are more effort to write, and can be daunting to read. I like the wiki format, which allows you to grow as needed, starting from a FAQ and ending in a handbook if you desire.


That’s also true! But in my experience, once you start a wiki, you always end up with lots of abandoned and half-made up pages. Or, in the case of faqs, a lot of links and redundancy.

I’d prefer to see a bit more focus with documentation, probably like a Wikibook. So it’s collaborative and open, but it’s also more focused on specific subjects.


I agree with this! I think a wiki could be very helpful, but we should probably limit who can edit it (or at least edit some pages). I share @nolo 's concerns about a sprawling wiki with half-completed and/or outdated pages. I’m not too familiar with Wikibook but it seems like the right direction. Hopefully we can make the interface a bit less clunky and more streamlined haha

1 Like

Not sure if I understood this correctly.
If is about the front page, that a person sees when they land on the website, from my perspective is very important to convey what is about. It can be a person that has no idea what the term “HospEx” means, a person that has never heard of Couchsurfing, BeWelcome, WarmShowers, HospitalityClub, You name it. I am talking a person that is totally new to all this. The website, through its main page must convey what is it about. As clearly as possible.
This is a good example which from my point of view (also because I am a member of it) does very well through its main page: On the main page is clearly written what the entire concept is about, what people that join can do thanks to it and what to expect.
If manages to convey clearly through its main page to everybody what is all about (not only to those that are already familiar to hospitality exchange) then will be a great achievement from the start because the people that will join will have a clear idea also about how to use it and is likely that they will then use it as WE mean it and so many “side-effects” will already be prevented from the very start.

Really like the approach on the Black Lives Matter site. They have a section Resources where several toolkits are presented and offered for download:

I think this approach helps a lot in having to define what are the central issues and actions and how to support good practice around them. As: organising events (or building local community in general), naming and handling harmful behaviour (or building and sustaining trust), expectations around hospitality (could call it a hospitality pledge)

1 Like