Tuesday, February 10, 2009

Readers Needed!

One of our key requirements for the release next Tuesday is improved documentation. Documentation is key, because it's the doorway through which new users will enter the world of Parrot. I've been doing a lot of work on documentation recently, along with several of the other developers. The problem is that from inside the project we can't always see where the holes are, and what the confusing bits are going to be. So, I'm asking for a little help from people who aren't current Parrot users or developers:

We need you!

We need people to read over the documentation and find the problem spots. What parts are confusing? What material isn't well covered, or isn't covered at all? What do you wish we talked about more? What information do you need in order to get started working with Parrot?

You can check out the source repository using SVN from https://svn.parrot.org/parrot/trunk/, you can find our documentation in the docs/ directory. Many of the files here, although not all of them, are used to populate our online documentation too (the online documentation has it's own problems too). We have a comprehensive book in development in the directory docs/book/, which contains a lot of material arranged in a linear narrative. All these things need some help.

We need suggestions, comments, even questions. Because answering your questions will help us to identify the information that is missing from our docs. We need patches, if you're able and want to contribute. Leave comments here on this blog with ideas, open a ticket at trac, or post a message to our mailinglist. It doesn't matter how you send us your reviews and your fixes, so long as you send a lot of them! We need help from readers and reviewers, especially people who aren't current Parrot users or developers, people who don't already have the answers. We need your help.


hexcoder said...

in the book chapter 02, section 2.2.2
after running nqp (whatever that is, it is not explained before), there is an unfinished sentence:
'With a few simple examples, you have'

In chapter 'Build requirements' I would like to see a more clear seperation of required and optional components.

In chapter 'Parrot; source code' a typo 'the best option is' instead of 'the best options is'.

more to come...

Whiteknight said...

Thanks hexcoder! I've committed a few updates to this file in r36674 and r36675. These issues should be resolved now.