Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

first draft of landing page #6

Merged
merged 19 commits into from
Jun 3, 2019
Merged

first draft of landing page #6

merged 19 commits into from
Jun 3, 2019

Conversation

vincerubinetti
Copy link
Collaborator

@vincerubinetti vincerubinetti commented May 20, 2019

index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
Copy link
Member

@dhimmel dhimmel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fantastic job thus far. Some minor comments for you to consider.

One thing that is missing is the disambiguation of the different manubot products / workflows. This doesn't necessarily have to be on the homepage and could be in docs or getting started, but just wanted to note that.

I'll draft up the acknowledgements stuff.

index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
index.html Outdated
Manuscripts are the primary basis of scholarly communication, yet the process of creating them has not kept in step with the advancement of technology or the evolving best-practices of science.<br />
<br />
Traditionally, authoring of manuscripts takes place in a very closed manner.
While most scientific material is eventually distributed to some kind of public medium, the process of developing and reviewing the material is usually done in private, contained to a handful of individuals.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A key point here is the delays of the traditional publishing process discussed in https://www.nature.com/news/does-it-take-too-long-to-publish-research-1.19320

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll put this in. Additionally, if you have relevant links to the other points i list in the paragraph, that would be great to show people.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cc @agitter and reminder to @dhimmel

Links to papers or any kind of references (even if they're informal) would be good to have for the "our philosophy" section. Helps back up our claims of what is wrong with the current system and/or how we fix those problems.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are some references that may be relevant:

They aren't perfectly aligned with the Manubot philosophy but will give you some options to consider.

@dhimmel
Copy link
Member

dhimmel commented May 21, 2019

0109415 re-wrapped all text.

@dhimmel
Copy link
Member

dhimmel commented May 22, 2019

Regarding acknowledgements for the homepage, what about the following text:


We would like to thank the contributors and funders whose support makes this project possible.

Specifically, Manubot development has been financially supported by the Alfred P. Sloan Foundation in Grant G-2018-11163 and the Gordon & Betty Moore Foundation in Grant GBMF4552.

As an open source project, Manubot depends on its network of maintainers, contributors, and users. The project is led by Daniel Himmelstein in the Greene Lab at University of Pennsylvania and Anthony Gitter at University of Wisconsin-Madison and Morgridge Institute for Research. See the acknowledgements here and the contributors to the codebase for a more complete list of individuals that have made Manubot possible.


I'd also potentially like to name @vincerubinetti and @slochower in the final paragraph... But my main worry is static contribution text becoming outdated and then future contributors being left out. Not sure what the best solution is. We could say "Frontend development is led by Vincent Rubinetti". However I don't know how to succinctly characterize @slochower's role because it is so varied. CC @agitter @cgreene

@vincerubinetti
Copy link
Collaborator Author

@dhimmel i think it's fine to defer to some other place (like github) for the other contributors. I'll incorporate your comments above and also write a sentence about that in the acknowledgements.

Copy link
Member

@agitter agitter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is looking great so far

index.html Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
<br />
Traditionally, authoring of manuscripts takes place in a closed manner.
While most scientific material is eventually distributed to some kind of public medium, the process of developing and reviewing the material is usually done in private, contained to a handful of individuals.
The tools used are often outmoded, restrictive, and overall poorly-suited for the task of collaborative, scientific writing.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This phrasing may beg the question "what's wrong with Google Docs"? Do we want to draw more language from the meta review to more precisely contrast Manubot with existing collaborative writing tools?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried to capture this with "poorly suited to scientific writing", which I think is where google docs fails.

Overall, I think we need to think of the landing page as a giant billboard/poster for Manubot, just key bullet points, very high level language, and let other pages go into more detail. I think it's fine to be more vague here. We can have an FAQ page in the docs that we can link to on the landing page that can include "Why not just use Google Docs?"

</div>
<div class="row">
<div>
As an open source project, Manubot relies on a community of maintainers, contributors, and users.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we do decide we want to list some of the main contributors or project leads like @slochower and @vincerubinetti, we could name something like a "steering committee" that indicates their influence in defining what Manubot is. That wouldn't need to be maintained much as new contributors join.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the idea of a steering committee.

@vincerubinetti
Copy link
Collaborator Author

@agitter @dhimmel I'll keep a live preview of my latest (local) changes at https://www.vincentrubinetti.com/manubot/ since it's hard to visualize the site just looking at the raw html.

<div class="row flex_wrap_reverse">
<div class="col_text">
<div class="col_header">
<i class="fas fa-hand-point-up fa-lg"></i> Beautiful and interactive
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In your HTML preview I noticed that this icon looks like it is pointing to the Automated and continuous image above, not the image to the right. Maybe use the font awesome comments icon for "public annotations" or mouse-pointer for "interactive"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that hand icon is pretty firmly associated with a mouse cursor rather than pointing in a direction, nowadays. We could use mouse-pointer, though I prefer the hand to indicate that we've thought about mobile (touch devices) too, which is hugely important and something that a lot of the other tools don't support (like lens viewer).

I understand comments w/ the annotations plugin, but that's just one of many. I was thinking of having something more vague.

What about something more vague like eye star or bolt.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like bolt. I agree that comments may be too narrow. Looking at it again, even hand-point-up isn't too bad, and I do like that it indicates mobile compatibility.

@slochower
Copy link

I have fielded questions related to whether (or how) Manubot is useful for projects that "aren't collaborative". Based on context, I mentally rephrase the question as: why should one use Manubot early in a project, when one may be working mostly alone or just with a PI? I explain that using Manubot -- and in particular, putting stuff out in the open -- can help find collaborators.

I think some people (graduate students, in this context) view Manubot as a tool for big groups who want to write papers together (again, based on some personal conversations). That's true in some cases (like Deep Review) but not all cases. Maybe we can make the point on manubot.org that Manubot, and the philosophy behind Manubot, is not just a tool for pre-existing organizations to publish progress reports.

@agitter
Copy link
Member

agitter commented May 29, 2019

Good points @slochower. We want to make it obvious that Manubot supports many different use cases, not just deep-review-style large collaboration.

What if we add a Why use Manubot? section with 3-4 hypothetical users after the The best parts section?

Jenny loves reproducibility. She keeps versioned code, figures, and summary statistics in a GitHub repository and uses Manubot to automatically update figures and data in her manuscript.

Rodrigo wants to improve his work based on feedback from his scientific peers. He uses Manubot to write his paper in private. When a complete draft is ready, he makes it public and revises it based on pull requests, issues, and comments from the community.

We could have another for large collaborative writing or one for interactivity. These hypothetical stories may be more direct in conveying our philosophy than keywords about being open and provenanced. (The keywords could stay too. This would be in addition to the Our philosophy section.)

@vincerubinetti
Copy link
Collaborator Author

vincerubinetti commented May 29, 2019

@slochower We sort of cover this with "Coordinate teams of any size with ease." and "Spontaneous and cross-discipline contributions. Organic and wide-spread discovery and dissemination of knowledge", though I agree it could be a little more clear and upfront.

@agitter I like those two examples. Another variant of that we could do is sort of "testimonials". I see this a lot with other software I use. The website will have a couple of profressionals say how they use the tool and how it helps them. So we could have a quotes from you or David saying basically the same thing, eg "I use manubot to write my paper in private, then open it up when a draft is a ready".

Edit Maybe this more appropriately belongs in an FAQ section. "Is Manubot only for big teams? No."

@agitter
Copy link
Member

agitter commented May 29, 2019

@vincerubinetti real testimonials would work better than hypothetical ones, but do we have enough users who could highlight the specific features we want? Ideally the testimonials would come from users who are not core members of the Manubot team.

@vincerubinetti
Copy link
Collaborator Author

Ideally the testimonials would come from users who are not core members of the Manubot team.

Agreed. Doesn't seem like we have enough right now. We can ask for testimonials (I think that's okay to do), but we probably still wont have enough. Just something to consider for later.

@dhimmel
Copy link
Member

dhimmel commented May 29, 2019

The "Why use Manubot?" / "Testimonials" section could be nice. Although I'm in favor of us merging this PR sooner rather than later and then having separate PRs for new sections... just so we can keep discussion straightforward.

@agitter
Copy link
Member

agitter commented May 29, 2019

Yes, let's merge this soon and iterate in separate PRs.

Edit: moved this new section to #7 to keep it out of the scope of this PR

@vincerubinetti
Copy link
Collaborator Author

vincerubinetti commented May 29, 2019

This is ready to merge after review approval.

index.html Outdated Show resolved Hide resolved
Copy link
Member

@dhimmel dhimmel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After minor comments by @agitter and me (in this review) are addressed, looks good to me.

index.html Show resolved Hide resolved
index.html Outdated Show resolved Hide resolved
@agitter
Copy link
Member

agitter commented Jun 2, 2019

I think this is ready to merge now. @dhimmel do you agree?

@slochower
Copy link

Want to add the steering committee information or do it in separate PR?

@dhimmel
Copy link
Member

dhimmel commented Jun 2, 2019

Yes. We can do steering committee in subsequent PR. @vincerubinetti squash merge at will.

@vincerubinetti vincerubinetti merged commit 14fd2de into manubot:master Jun 3, 2019
@vincerubinetti vincerubinetti deleted the dev branch June 3, 2019 16:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants