Real content added.

davidbauer authored
revision 92dae3014150d2ec6b4a3f2e496f30ab4018340a
Your project is alive!

This is your document. Click the small white 'Edit' button above to make changes to this file and start writing. Until then, here's a quick primer on how Penflip works:

## Projects

Right now, you're looking at the project page for your new project. The project page is the headquarters for you and your collaborators - you can write and edit, invite collaborators, have discussions, browse changes, see project activity, export your project, and more.

## Writing

You'll see 'Edit' buttons across the project. Clicking any of these buttons will take you into a distraction-free 'writing mode', similar to Google Docs and other writing tools. Everything is written with [Markdown]( For an explanation on why markdown is awesome for writing, [read this](

## Versions

Every project has a master version. Whenever you invite somebody to your project, a new version will automatically be created for them, and all of their changes will be made on their own version. When a collaborator is ready to submit their changes into the master version, they'll create a Merge Request.

## Merge Requests

A Merge Request is a group of changes to your project. All merge requests go into the master version. As the project owner, you control the merge requests: you can accept them, ignore them, and comment on them to suggest changes. When you accept a Merge Request, the master version of your project will be updated with those changes.
Below the line comments are finally being challenged as the default format for reader contributions on news sites. Per paragraph annotations as seen on Medium and Quartz have recently gained some traction. They are, rightly so, praised as a more intuitive and inclusive way to comment on a subject matter.

However, annotations won't work for all kinds of contributions, just like comments at the end of an article didn't.

The simple and hard truth is that there is no one-size-fits-all solution. Let's have a look at the spectrum of possible user contributions and what format might fit each of them.

This is not meant to provide a solution – I wish I had one. It's meant to smash the notion that annotations are the new best practice for comments and to spark a conversation about where we can take user contributions. It's a wicked problem worth solving, so let's try this together.

## Motivation for contribution: Citation needed!
Possible solution: Mark and flag the part that needs to be supported by a link, pretty much like on Wikipedia. Disappears once the link is added.

## Hey, this fact seems wrong, double-check it!
Mark and flag the part that you feel needs be checked. The more people challenge a passage, the more it fades out. The author of the piece can dismiss the challenges or change the passage.

## I've got some more facts on this
Per paragraph annotation, either public or only visible to the author of the piece.

## I don't understand this
One-click per paragraph annotation, giving the author a heatmap of the parts of his article people understand the least.

## Here's some further reading on the subject matter
Per paragraph annotation or a separate Wiki-style list of further reading (Medium already has this feature)

## I've got insider information to share on this subject matter
Option to privately and securely contact author of the piece.

## I've got additional material on the subject matter
Could be an «article inbox» to which users could send material, either to be displayed right away or only for the author's eyes.

## There's a typo, fix it!
User fixes it, sends a Github-like pull request to have the edit accepted. These requests could go directly to the correction department for review.

## I want to express my opinion about this part
Per paragraph annotation, maybe enhanced with sentiment data (agree, neutral, disagree).

## I want to express my opinion about the whole piece
Traditional comments, enhanced with sentiment data (agree, neutral, disagree) and user related data (age, political views, profession, etc.). Maybe with Quora-like limitation: one comment per person.

## I disagree with the whole piece and want to write a reposte
Same as above, plus: Submit your comment for reposte.

## I want to discuss the matter with other readers of the piece
Open a thread and own it (the Gawker-model). Other option: Realtime chat of people who are on the same page, fleeting, not recorded (like Husky Chat).

## I want to discuss the matter with people who I actually like to discuss with
Open a thread that is only visible to people you invite or who are in a predefined group with you (similar to Facebook Groups).

## I just want to reach the public (and troll)
Whatever your intentions, this motivation will be one of the most dominant ones. Limit number of contributions a user can post based on their track record.

## I have an idea for a follow up piece on this
Again, «article inbox» to which users could send their ideas, either to be displayed right away or only for the author's eyes.

## I'm a person addressed in the piece and want to engage in the conversation
Verify users and display their contributions, of whatever type they may be, more prominently in the piece they are addressed in.

## I have a question
Separate list of questions to the author, which he can answer inline or with a new story.


You see, this is a pretty big mess. Which is my point.

The big challenge, of course, is to find a mix of tools and interface elements meet most of these diverse needs, without making things so difficult that nobody likes to contribute any longer.

One way to think about this is enabling only certain ways to contribute, based on what kind of piece it is or who the user is (as in: you need to earn a «reputation» to be granted access to certain tools).

You could also, on the other end, allow readers to define what kind of contributions they are interested in and let them hide the other types.

Again, don't take this list as a blueprint. It's a conversation starter. Let me know what you think (and, yes, sorry for the limited commenting options...)!