Let's define what Documentation is?

Website, Documentation, and Discourse
21

If you look at our current wiki, it’s divided into different segments:

1.) Developers
2.) Community
3.) Podmin Resources
4.) Guidelines and Policies

Each of these sections are further broken down into specialized sub-sections, covering quite a range of topics.

https://github.com/diaspora/diaspora/wiki

This could probably be tweaked more for the sake of granularity. I think some kinds of documentation belong on a subdomain, separated from the rest of the wiki for very specific purposes. (documentation on an API could be located at api.diasporaproject.org, federation and architecture explanations could be at developer.diasporaproject.org, and a robust field guide could be put together covering running and working with Diaspora at docs.diasporaproject.org, with instructions on how to modify it yourself, for example)

Each of these subdomains could be linked from the frontpage of a redesigned central site. Some good examples of how this is done:

-Gnome Project (Gnome.org)
-The Elementary Project (http://elementaryos.org/)
-The KDE Project (http://kde.org/)
-To a lesser, but still useful, extent, the Ubuntu project (http://www.ubuntu.com/community)

Each of these designs maintain two different things, and do a pretty good job of it:

1.) A visually attractive front-end
2.) A design that showcases what’s going on in a community, while also not forgetting to link to important resources.

22

Madame, no I’m not, but I was only trying to explain the documentation in software projects in general. Diaspora is not only software.

23

Just thought I would point out that Diaspora being a Ruby-on-Rails applications does come with documented code…
For example, you can look up any of the gems in use and find documentation of it’s usage.
The thing we are lacking is a clear way of defining the code that was added by Diaspora from the code that was added by gems.
Currently we are in process of that though by moving to a more “modular” architecture…

24

Ok. WAIT.

I don’t know what I have to say to make you hear (read) what I’m trying to point out.

I can’t believe that you are so thick. Come on.

Documentation for technical people is fine in the code, in a wiki, whatever or wherever. YOU ALL are savvy enough to dig and search and peel whatever you need to dig and search and peel to get under the layers of cruft to get to the answer you are looking for.

The folks I’m talking about are the SIMPLE, non-technical users.

I have been through this circle over and over again. Community IS NOT just CODERS. Or is it?

Can’t you get it?

Do you REALLY think that the only people who will use this platform are CODERS or EARLY ADOPTERS, like us?

If you really want to get this project off the ground like a rocket to Mars, you have to include YOUR GRANDPARENTS as users. People like that. Get it???

You have to include people who do NOT have the time to search and search through technobabble that they cannot understand.

I’m not saying DON’T do documentation for coders, in the code or in a wiki I’m saying WHAT ABOUT all the other people who need help who just want to use the stream?

What are you doing to make it easy to find? Easy to search? Easy to understand?

Or do you just not care about that?

25

MP, capital letter will not help you getting trough with your message. Telling people that they are “thick” will not help your case either.

“I have been through this circle over and over again. Community IS NOT just CODERS. Or is it?” Nobody here i saying that it is, if you look at https://github.com/diaspora/diaspora/wiki you will see that Diaspora do not define community in such narrow way either.

Now, can the documentation get better for ALL members in the Diaspora community? It sure can, I think most people feel that way.

26

MP, if you are truly passionate about the “simple” non-technical user, why not try to find some reference project that we can use as inspiration improving that part of the Diaspora documentation? Did you visit http://elementaryos.org/support? What do you think about it?

27

MP, or how about Mozilla Help? E.g. https://support.mozilla.org/en-US/kb/what-browserid-and-how-does-it-work
What do think about this?

28

Sorry I didn’t mean to be harsh. It has to do with being here already. It’s the same thing as before. Community doesn’t seem to include the users. Community seems to include devs and only devs. When I see as much effort being put into defining real community that is being put into looking for tools and deciding protocols, then I will change my mind. I’m not going to try to speak to people who aren’t listening. There is a history of that happening already. It’s not the first time. It’s not my job (and only me) to make others see it. If they can’t see it they can’t see it.

I’m afraid I cannot write much more right now. Things to do.

29

Why is a wiki not a good enough documentation platform for users who aren’t coders? Wikipedia is one of the most popular websites in the world, so popular that it helped put Encyclopedia Britannica out of print, I think the average internet user knows how to use a wiki (and the search engines definitely know how to index it). MediaWiki is the exact same software Wikipedia uses, it’s just a matter of structuring and organizing the documentation so that it’s easy to find and easy to use.

Nobody is saying we don’t need documentation for non-technical people, but to get to that point, first we have to clean up and document what we already have. If even the more technical people like developers and podmins don’t have good documentation to tell them how everything works, how is anyone going to write the documentation for non-technical users?

30

@Steve: I agree with everything you are saying. A wiki (as a tool) isn’t the problem, the problem is that there has been a rash of tools being thrown into the mix to deal with documentation and discourse (in the community) and a confusing path to find these tools. It’s not the tools, it’s the tool use. If you do find one of these many offsite tooks, it’s not straightforward to know how to use them in a way that is acceptable, and whether the info housed in them is dependable. It is difficult to know where to find help. It’s difficult to read what is the cultural norm. Maybe not for people who are tech savvy, which I’d say is all of the members here. I’m talking about non-technical users. I’m advocating for them.

If there were a wiki that gave real information, and it was kept up, and it was links to it were pervasive on the main site, then that would be a solution. But the problem is that there have been several of these tools and they are inconsistently used, they are not kept updated, it’s not clear who even runs them.

What is difficult to take is that there has been a lack of discipline, perhaps because it’s not “sexy” to deal with documentation, and it’s not “sexy” to deal with terms of service and privacy policies. Or to discuss what kind of community (broadly defined to include all participants) that we want. But these things are the very things that are the glue to a healthy vibrant community.

My voiced displeasure is not intended to be cutting or pedantic. It is caused by my skepticism that nothing is going to change, and that the pattern of finding another “better tool” and getting into yet another wonky discussion about why one tool is better than another, is just another cycle of the same habits of excellence that got us here in the first place. Would I like to be proved wrong? Certainly!

But even Einstein said that insanity is doing the same exact thing and expecting different results.

I don’t mean disrespect to anyone here in the least.

31

The idea is to get all these tools into one central place (that place will be joindiaspora.org), But that does take time, those tools need to be integrated in a way that allows everyone in the community to find them, use them and (if need be) edit them to keep them up to date.

As far as defining what is the cultural norm, that’s something that will (and must) evolve as the community grows, nobody here can dictate what the cultural norms for the entire community can be (nor should we). I know of no document that dictates what the cultural norm is on Facebook or Twitter and people seem to have no problem using them and figuring it out, humans are social animals by our very nature and we’ve been figuring out ways to interact with each other for thousands of years.

You asked earlier “What do I do if someone is trolling me?” and my response would be “Is it any of my business to tell you what to do and how to interact with other people?” It would be impossible to enforce any kind of strict rules for the community as a whole, we’re not building a huge monolithic site like Facebook here but a network of independent sites, but the tools are there for you to manage your interactions as you see fit (you can share with whoever you want, you can block whoever you want, you can post things as publicly or privately as you want).

32

@Steven: Thanks for your reply. I agree that we should not dictate cultural norms. I don’t think that’s what I’m saying.

If the interface alone were all things to all people then there would be no problems. I think that accepting that it won’t be ever this, is right. That means that we have to have other ways of supporting people in the community beyond the tool. I don’t think I’m saying I know the answers, I’m merely making suggestions for solutions for challenges I have witnessed here in the community, and I mean the entire community, not just the coders (the coders are people too, I am not denigrating them by saying that, OK???).

I think setting up guidelines is perfectly acceptable. I also think having a terms of service and a privacy policy is mandatory when dealing with something as precious as anyone’s privacy and data. It seems reckless not to have one prominently posted.

At least FaceBook says they have rights to do anything they want with your content. Even allow the police to print out your face in a photo taken at a friend’s party and present it in a murder trial of some guy you only met at that party, and allow a journalist to publish that public record like in the New York Times. (That has happened!!!) That is what FB’s TOS allows to happen. What do you think having no Terms of Service will allow to happen? 5, 10, 20 years from now?

Trolling, which I am holding up as an example of bad behavior among many others, can happen BECAUSE there is no clear TOS. There are no clearly stated consequences for bad behavior that is reasonably deemed threatening to others. Having guidelines tells everyone, if you are trolled here are some steps you can take, here are some steps to prevent it. Sometimes people saying “don’t feed the troll.” is not enough. Sometimes it is. If we as a community say how we feel about trolling, and indicate this is what we will/can do if we learn of valid cases of trolling. It’s not dictating anything because it’s only encouraging positive behavior. It’s not telling people you have to be good or else, and then leaving the definition of “good” up for grabs. These are guidelines and policies. I don’t see anything wrong with that. Do you? Unless you are saying that everyone should be free to be a troll? I can’t think that’s what you mean?

33

I agree that terms of service and a privacy policy is necessary, but there’s literally no way a network-wide terms of service or privacy policy could ever be enforced (practically or legally). Even if we were to sit here and come up with the perfect, bulletproof TOS and privacy policies and include them with the software there’s absolutely nothing to stop me from setting up my own pod with my own policies. In fact, the license says I can do it, the AGPL specifically says “You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License.” and requiring me to abide by a certain TOS or privacy policy on my own pod would be a further restriction to the rights granted under the license.

Terms of service and privacy policies (and cookie policies too, if they’re serving up any EU traffic) are something every podmin should have in place, but nobody here has any authority to enforce that.

What will we do if we learn of valid cases of trolling? What can we do? We can’t ban someone, that’s technically impossible on a federated network. A podmin can ban a user on their pod, but nothing stops them from joining another pod or setting up their own. Since we also (under the current federation protocol, at least) can’t cut off any other pod from the network, any rules about trolling would be impossible to enforce.

34

:slight_smile: @Steven: Who said we have to come up with a bullet proof TOS/PP? But it would speak loudly for a pod who doesn’t have one that perhaps I wouldn’t want to be there. And where there is one, the podmin is willing to make some kind of covenant for what he or she deems as what is acceptable use and what privacy(or lack of it) means on that pod. What is wrong with that?

So I think what you are saying is if an AGPL is states, “you may not post a privacy policy if you use this software.” then it means that the podmin is in breech of doing so if it is to protect his users?

Then does it mean that anyone can do anything with the content that is on the pods, that is in the databases at any given time now and in the future, even if it goes against the stated purpose of starting Diaspora in the first place? Which as I understand it was to be privacy sensitive and to respect the speech of others. Or whatever their intentions were. Not that I’m exactly clear anymore. :slight_smile:

I think that a podmin does have every right to enforce his or her own policy. And the software should allow for that. That’s like getting into a car without safety belts. I mean a car today, not in 1906. Who would do that? Not me. Then, what about the users?

I can’t speak specifically about trolling, and I don’t mean to speak specifically about trolling, I was only pointing to it off the top of my head as behavior that everyone seems to agree is unwelcome behavior and that it hurts people. I think it’s a convention that hate speech is unwelcome in a forum like this. I don’t think Diaspora was founded to promote hate speech and if it were, we wouldn’t have the majority of the kind of people here that we have here. But what about when hate speech occurs? That can be a serious offense in some countries.

As I understand it, which isn’t all that much, federation is a big issue and under discussion. It seems few people are happy with it. Perhaps because of trolling? I don’t really know. Perhaps a podmin wants to be free to have control over which pods his or her pod federates with? I suppose there are benefits besides preventing trolling to do that. But a policy still should be in place.

35

Sorry for the delay in getting back to this, had a lot of other things to do.

No, the AGPL definitely doesn’t mean that a podmin can’t post a TOS or privacy policy to use the software. The podmin (as a user of the software) can do almost anything they want with their own pod, the AGPL and opensource licenses in general give you a lot of freedom in how you use the software. You’re right that the podmin has every right to enforce his or her own policy, that’s exactly my point. We (developers, podmins, or anyone else) as distributors of the software have no right under the AGPL to require the podmin to do so, since that would be an additional restriction on the use or distribution of the software/ I even agree that the software should allow for that, in fact I created a plugin several months ago (mostly as a proof of concept, but it works) to make it easy for a podmin to do exactly that. :slight_smile:

As far as what anyone can do with the content on the pods, that’s a tricky question, because of the nature of federated networks and the fact that a network-wide privacy policy would be technically and legally impossible to enforce (and a privacy policy that’s impossible to enforce is almost as useful as no privacy policy at all). Hypothetically, if you and I are both podmins and we both have different privacy policies… first of all, our privacy policies would have to allow for federation or we’d be in violation of our own rules just by running the software. Now, if I post something on my pod and it’s federated to yours, wouldn’t the copy on your pod be subject to your privacy policy and not mine?

As far as trolling, threats, hate speech and things of that sort… most countries have laws to cover that sort of thing. No TOS or privacy policy (or lack thereof) can or should be a license to violate those laws, at least here in the U.S. courts have ruled many times that a contract to break the law is no contract. Personally, if I were running a public pod my policies would allow for me to ban users and/or cooperate with law enforcement in cases like that, but even if they didn’t, surely a court can and would compel me to put the law ahead of my own personal set of rules. Of course, banning a user (as I said earlier) is completely pointless on a network where anyone can join any pod or create their own… but in legitimate cases of harassment, threats or hate speech where law enforcement is involved, privacy policy or not, law enforcement has legal ways of getting the information they need to do their job. We also… as podmins, and users (as developers we can’t do much more than provide the tools)… have some responsibility to police ourselves on those matters. If you see someone promoting hate speech, call them out on it, make sure other people know that this is probably someone they don’t want to be associated with. Online communities have existed for a lot longer than the modern, popular internet has (I come from the days of dialup BBS networks like FIDOnet) and this kind of self-regulating has always been a lot more effective than handing down rules from above.

As far as I know (and I could be wrong), the biggest issue with federation is the fact that it doesn’t work the way it should. Posts don’t always make it to other pods, hashtags don’t federate the way you’d expect them to do… purely technical issues.

Should a podmin have control over which pods they federate with? I think so, but that’s a difficult thing to do in a completely decentralized network. Sure, you could set rules in your firewall or we could even add tools to allow a podmin to block certain pods from communicating with his/her pod… but that’s about as far as it can go. Back in the day we had a solution for that, with the BBS networks (I’m thinking of ideas from both FIDOnet and WWIVnet here) we had a central network coordinator who controlled the list of “nodes” on the network, then local area and regional coordinators who took some of the workload off of the central network coordinator. With Diaspora I don’t think we can do that because 1) that doesn’t really scale to a large, worldwide network like the internet and 2) that completely kills one of the core ideas of Diaspora, the idea of creating a decentralized social network where anyone can add their own “node” to the network by simply installing the software.

36

@Steven: Thank you for your long and thoughtful reply. I appreciate long posts, if you haven’t figured that out. :slight_smile: I also appreciate the tone of your reply.

I appreciate that you are willing to exhibit patience and to explain things that may not be clear to someone who isn’t a coder. Your explanation will be helpful for others who wish to better understand the nature of the beast when discussing TOS/PP on a network like D*. That is what I’m trying to kickstart here in this forum at Loom.

I realize that I am naive about licenses and all that, but I’m not sure the point of taking the fifth amendment when it comes to posting (or not posting) a TOS/PP. I don’t understand why Diaspora will not encourage a TOS/PP and recommend a boilerplate.

We agree that these cannot be policed.

Still… by not having one, it is a breech of trust. I don’t see any way around it. I’m sorry I was confused by your reference of your plugin. What does it do exactly?

Also why must a pod have to federate? Who decides that? Aren’t there private pods? If a pod must federate or risk being in breech of the license then why not ask that all podmins have a TOS/PP (of their choosing) and have it clearly posted in simple direct language? What is the difference?

Really, I am not about controlling the content, per se. I hope that is understood by everyone here. What I am for is full disclosure about using the Diaspora tools. (I see the entire platform as a tool, btw, even though I’m aware there are a series of tools evident and possible under the umbrella of the platform).

Users should understand things like the tool is not fully private, but semi private. Users should be extremely clear what it means to make a public post and what happens to their content and how their content may be vulnerable. IF it should happen that there is a breech of content or privacy BECAUSE of conflicting pod policies, I’d proffer that it should be the mandate of the D* Fo to wade in and deliberate that.

The reason for doing this has to do with taking a stand for the importance, value, and respect for the privacy of others.

Up to now I haven’t seen an attitude of sensitivity for the privacy of others. Quite the opposite. The attitude is very hands off. The explanation is that “it is technologically impossible to block that from happening.”

That is what good policies are meant to do. To promote good will, not to foster bad will. Waiting around until someone is humiliated and takes legal action or something far worse, like political or physical harm is really reckless in my opinion.

I think the only way to come to a possible solution is to have these conversations we are having. The answer will emerge from discussing it. But to think there is a silver bullet solution is wrongheaded. I’m not advocating silver bullets and I never have.

Thanks again for the chat!

37

The plugin I created a few months ago was basically a proof of concept. It uses a Rails engine (one of the built-in plugin systems of the Rails framework) and something called Deface to add links to a TOS and Privacy Policy on every page. It doesn’t include any policies by default, but it generates the blank template pages that the podmin can edit. It’s published to RubyGems as pod_legal and released under the same license as Diaspora, so any podmin can use it by adding one line to their Gemfile and running a Rails generator to generate the routes and the blank templates.

The reason a pod must federate doesn’t have to do with the license, the AGPL doesn’t say anything about that, it’s a technical limitation of the software. As it stands now, unless you want to maintain your own modified version of the software and keep it up to date (the way Pistos did, but for different reasons) there’s no way to turn federation off. A private pod, at least at this point in time, just means that the pod is not open to user registrations and the podmin has complete control over who has an account and who doesn’t.

38

I don’t think anyone is suggesting that documentation should only comprise technical, development documentation - it’s more the case that the majority of people who have come to Loomio are developers who are keen to help restart the development of Diaspora code, which is a much-needed activity, and so are therefore focused as far as documentation goes on improving the documentation of the code to help others (1) take part in developing the software and (2) help improve the network by doing things such as running pods.

Yes, documentation has to include wider things as well, such as terms of use, policies, governance, simple ‘how to’ stuff for new people, FAQs, and so on. There are bits of all of this on the Wiki and the diasporafoundation.org site, but what is there needs improving and updating, and there needs to be a lot more than currently exists.

I’m a non-coder (apart from some HTML and CSS, but nothing that would be of use to Diaspora), and am keen to help in the development of the non-technical documentation.

It’s good that some people are focused on developing the software and developing the documentation for the software code, because without that it’s harder for new developers to join in, and especially now that this is a community project, that has to be one of the main priorities at the moment. But it will be good for others to work on non-technical documentation. Both are needed.