TWiki> Public Web>DocumentationSprints (revision 7)EditAttach

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 couple of weeks) 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 documentation sprints

None at the moment. The next documentation sprint will be about input/output of data from/to ASCII files. The sprint will run from Tuesday 11th to Monday 24th October 2011.

Past documentation sprints

The Editorial Board is working to include the results of this sprint 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 | r9 < r8 < r7 < r6 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r7 - 2011-10-10 - DavideRizzo
 
This site is powered by the TWiki collaboration platform Powered by Perl