-
Notifications
You must be signed in to change notification settings - Fork 652
GSoD FAQ
Frequently Asked Questions for Google Season of Docs with MDAnalysis.
Please read
- GSoD 2019 with MDAnalysis blog post
- Project ideas page
- Google's Technical Writer Guide (including eligibility requirements) and the Program Rules
- Google's GSoD FAQ
We grouped questions and answers in broad categories:
If you have questions that are not answered here contact us on the developer mailing list and ask. We are happy to answer your questions.
All communication regarding GSoD is carried out publicly on the developer mailing list https://groups.google.com/forum/#!forum/mdnalysis-devel. The email address is mdnalysis-devel@googlegroups.com.
Note
- Initial emails are screened by moderators so first posting will only happen after a delay of a few hours.
- All replies go to the mailing list and not your private email address.
- Read the email replies through the public web interface https://groups.google.com/forum/#!forum/mdnalysis-devel or subscribe to mdnalysis-devel to get the emails.
All replies go to the developer mailing list and not your private email address.
Read the email replies through the public web interface https://groups.google.com/forum/#!forum/mdnalysis-devel or subscribe to mdnalysis-devel to get the emails.
Yes, please!
- When you introduce yourself, tell us how you successfully communicated technical ideas.
- Provide links to your work and add context – tell us, what you've done in the specific linked work and what you are particularly proud of or what you think worked well. Google's Technical Writer Guide says you must be "Able to demonstrate prior technical writing experience by submitting role descriptions and work samples." We would expect you submit samples of your work and explain how the samples demonstrate your abilities as a technical writer.
- Tell us about your scientific experience (e.g., if you used molecular dynamics simulations or MDAnalysis or other related software).
Projects are listed in the Project Ideas List together with approximate estimates of effort.
Yes, we envisaged that technical writers would do one of the shorter projects as a "starter project" and one of the longer ones for the remainder of the time. Ultimately you will have to write a proposal that shows convincingly how you will accomplish the work that you proposed.
No, you don't have to pick from the list. We are open to your own project proposal.
We suggest that you discuss your idea with us so that we can give you more insight into where your idea would fit into the broader requirements of the MDAnalysis project. You can also start with our project ideas and modify. In any case, we're happy to refine your idea together with you.
No, we don't think that this project on its own is sufficient for a whole GSoD. We estimated its effort to be about 25% of the total time.
If you think you can substantially broaden it then you might be able to make a full proposal work. Ultimately, your proposal has to satisfy our evaluation criteria.
Become familiar with MDAnalysis: What is it used for, how is it used.
Are you familiar with computer simulations of atoms and molecules? If not, learn a little bit about "molecular dynamics simulations". You can also watch the SciPy 2016 talk on MDAnalysis.
Work through the MDAnalysis Tutorial and get a feel for how MDAnalysis is used (and take notes of things you would improve – we know that our docs need improving, hence GSoD!)
We understand that making you use our software is a sizable initial ask but on the other hand, MDAnalysis is relatively complicated software that is used in research by many people and we doubt anyone could write documentation for it without actually trying to use it. We are happy to help answer questions as you go along.
We are happy to work with you on refining your project ideas, based on your experience.
Yes, definitely, you should contact us!
Our ideas is list is a starting point, and we want to learn from our technical writers how to do docs better. We look forward to hear more from you and how you think you can improve the MDAnalysis docs. We are happy to work with you to formulate the key ideas of your proposal.
Technical writers will have to submit a proposal for their planned work. MDAnalysis mentors will evaluate proposals.
See Creating a technical writing application.
Also look at our evaluation criteria.
Remember, we are happy to work with you to make your proposal great and a good fit for MDAnalysis!
We would expect a proposal to be at least a few pages of a structured document (at least 1,000 – 1,500 words, more is ok) that outlines what problems you are addressing and how you are going to solve them, with examples that gives us some idea what you will actually do. Include screen shots, diagrams, text snippets, etc. (you can include links to images hosted elsewhere for an example of a diagram that you would include). Detail is good as it allows us to make more informed decisions and shows us that you can familiarize with a new topic efficiently.
Include a time line that demonstrates feasibility.
A proposal needs to be more than a few bullet points. It needs to clearly convey your ideas and your approach so that we can easily evaluate it.
We will first assess your proposal following the recommended GSoD criteria (style, logic, layout, etc).
Ultimately, your proposal has to convince us of the following:
- You propose work that will substantially improve the user's experience with MDAnalysis (i.e., it will have impact).
- The work is feasible (i.e., you have the experience to successfully complete your project in the time frame of GSoD).
- Your project makes good use of the provided resources provided by GSoD (e.g., appropriate for the time frame that you get a stipend for, good use of mentors' time, ...)
Note that GSoD is a collaboration between technical writer and open source mentors. You do not need to know everything about MDAnalysis. But we need to be confident that this collaboration will be productive.