Documentation Sprints

Jump straight to the active and upcoming documentation sprints

What is a documentation sprint?

A documentation sprint is a collaborative effort to improve a portion of documentation: a section, a whole chapter, one or more entries of the User's Reference Manual. The aim is to focus effort on rapidly improving key areas of the documentation while inviting participation from as broad a community as possible.

How does it work?

  1. A portion of the documentation is transferred to a Google Docs document. That's just a common word processor interface, but it's online, in your browser.
  2. The sprint is announced. Anyone can edit and comment the document. See the next section for details.
  3. After a certain period (usually a week) the sprint is closed and all the changes accepted by the Editorial Board are included in the documentation.

How can I help?

It is easy to participate and takes just a few minutes per sprint:

  • Check the currently open sprints (see the bottom of this page).
  • Have a look at the documents on Google Docs.
  • Do one or more of the following:
    • Edit the text as you would do in any word processor. You do not need a Google account to edit. You can choose to leave your name or remain anonymous. Your contribution will be acknowledged if you leave your name.
    • Add a comment on the document as a whole by clicking the Discussion button at the top right corner of the window.
    • Comment on a portion of text by selecting it, right-clicking and choosing Comment.
    • Reply to any comment by clicking it and writing your answer.

Some recommendations

  • Make sure your browser is supported by Google Docs. See this page for details. Note: Firefox 3.6 and the latest Opera (11.50) also work well.
  • If you want to delete large portions of text, select it and choose Format --> Strikethrough, so that it's still visible to other users. You may also want to add a comment motivating your decision.
  • Hyperlinks to other sections and manuals are not kept in the conversion to Google Docs. If you want to propose the inclusion of links, make sure that they are not already present in the original documentation.
  • If you want to leave comments or questions, use the Discussion and Comment features of Google Docs (see previous section). Try to avoid writing comments directly in the text, since other contributors may overlook them.
  • The document is saved automatically, you don't have to worry about that.
  • If you have any doubts, just get in touch with the Editorial Board.

What's in it for me?

The more people take part in sprints...

  • the more improvements we include
  • the more errors we fix
  • the more we get to talk with users like you

I missed a sprint for my favorite task! How can I send feedback?

At any time you can contact the Editorial Board, or use the feedback icon in the HIPE documentation.

What happens after a sprint closes?

  • The Editorial Board approves a final version of the document.
  • The revised version is merged into the documentation.

Why Google Docs and not this TWiki?

We evaluated our TWiki platform, but decided against using it for two main reasons:

  • No WYSIWYG editor.
  • No way for external users to register and edit pages, not even in the public area.

If these shortcomings are fixed by a platform upgrade and a change in registration policy, we may consider moving the sprints to the TWiki.

Active and upcoming documentation sprints

None at the moment.

Note: for upcoming sprints, you can already see the Google documents, but you cannot edit or comment them until the sprint starts.

Follow us on Twitter or join the herschel_dp_hipe mailing list to be informed of upcoming sprints!

Past documentation sprints

  • Plotting (5th to 11th March 2012)
    • First half of the plotting chapter of the Data Analysis Guide.
    • Second half of the plotting chapter of the Data Analysis Guide.

The Editorial Board is working to include the results of these sprints into the documentation.

Hall of Fame

See who contributed to previous documentation sprints in the Hall of Fame.

Edit | Attach | Watch | Print version | History: r13 < r12 < r11 < r10 < r9 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r13 - 2012-03-15 - DavideRizzo
This site is powered by the TWiki collaboration platform Powered by Perl