anyone want to take over as the documentation-czar?

[Paul Grandjean]

Hey all,

I haven't had much time to dedicate to the documentation for quite sometime and I'm wondering....is there anyone out there who would like to lead/guide the effort?

It seems like there's currently a renewed interest in improving the docs and it would be nice to see this continue.  I'm just concerned that things will continue to lag if that person is myself.  People will be waiting on me to get back to them--perhaps waiting a lot.

It mostly takes someone to be a point-man/woman to help coordinate and guide people who want to contribute.  I'd be happy to assist my successor with getting started.

Current things that could (should?) be worked on with the docs.  This is mostly based on ideas and feedback that has floated around for the past year.

- turn the docs in to a wiki

- add a search capability

- edit, and add to, the WebDriver chapter

- complete the Sel-Grid chapter (Its been started and I'd like to continue contributing to this piece as I have tons of notes on this topic)

- update the RC chapter, there's info there that is likely no longer relevant

- review and improve Page Object information

- any other improvement that can be made

Paul

[Simon Stewart]

Hi Paul,

First of all, thanks for being the docs-czar for the past eternity. I
hope you continue to stay involved :)

Secondly, anyone up for this? It's a great way to help improve things
for new users, as well as expose all sorts of niceness for more
experienced devs....

Simon

> --
>
>

[Peter Gale]

Paul/Simon

This task could fit well with my current use and level of knowledge of Selenium, giving me the chance to take it up a notch or two ... and I should be able to get approval to commit some of my work time to the role given that we intended to use Selenium extensively.

What's the minimum level of effort do you think is necessary to make a good job of the task? A few hours a week perhaps?

Peter

> Date: Thu, 20 Sep 2012 12:00:39 +0100
> Subject: Re: [selenium-developers] anyone want to take over as the documentation-czar?
> From: simon.m...@gmail.com
> To: selenium-...@googlegroups.com

> --
>
>

[Simon Stewart]

Paul, have you got enough bandwidth to lead this conversation? Or
would you prefer me to do some of the heavy lifting. Happy either way
:)

Simon

On Thu, Sep 20, 2012 at 2:19 PM, Pradeep Bishnoi
<pradeep...@gmail.com> wrote:
> Hi Paul, Hi Simon,
>
> I would be more than happy to contribute some amount of time for the same.
>
> Thanks!
> /Pradeep

> --
>
>

[Luke Inman-Semerau]

I think I've by default been in charge of docs for a bit. But I don't like titles ;)

If anyone wants to make contributions to them I'm more than happy to help get it in! There's current flux and the build is broken ;) perfect time to make big changes! :-D

I highly encourage all of you to join us on IRC (freenode.net #selenium) I'm lukeis in there and am usually there daily (Pacific hours ~ I'm in San Francisco).

The things pointed out are very visible to me but I haven't had much time to spend on it. So I would love to discuss and coordinate any effort on them.

Anyone making more than a couple contributions we can get you commit access to the project :)

--

[Adam Goucher]

I'm likely going to regret saying this, but since I am currently
'minister without portfolio' on the official project I can be the point
person for this. Of course, I am not unknown for having opinions on
[many] things. Like /significantly/ de-emphasizing se-ide, page objects
all the time, etc.

(And I'll get cranky if commits that add/change functionality don't have
corresponding bits to the docs...)

-adam

[Santiago Suarez Ordoñez]

I'm late in the docs discussion, specially considering there's another thread discussing translations as well. Sorry about that.

I think this is a good time and opportunity to discuss a rewrite and reorganization of most of our docs.
The original content was written more than 4 years ago, and even though Luke and some other folks have been doing a great job adding new content and keeping it as relevant as their time allowed, it's hard to ignore that the project has moved long ways since the original chapter structure was decided and a big part of the content was written. This makes the overall docs experience rather confusing if not misleading, mainly for entry level users.
Based on that, I think it's worth considering starting from scratch, with a structure that is more focused in Selenium 2 (or WebDriver), that points users from all levels in the right direction from the get go.
I have been thinking about this for some time, but have been hesitant to bring it up as I personally don't have the time to execute such a project. My current plan was to bring this up closer to Se Conf 2013, thinking a good option was to make a workshop (or hackaton) where a reasonably sized group of attendees writing content would get us way closer to something that a group of contributors could take on, organize, clean and deliver.

The main requirement for such workshop to produce useful content would be a "leading team".
This would be a qualified group of people (ideally including active committers) to come up with:
- A sketch of chapters for high level content organization: Having this outlined correctly is fundamental for the success of the documentation.
- More detailed plans for each chapter: groups of attendees could collaborate on getting good content written for each specific section.
- A list of all the code examples that need to be written across all chapters: workshop attendees would be extremely helpful at writing and testing these in multiple languages before we can pull them inside the content

I any case, I don't know how this proposal goes with people's plans and expectations, but I thought I should put it on the table before it's too late and see what everyone thinks about such option.

Santi

--

[Paul Grandjean]

I can lead this conversation.  Yes, I'd like to help guide it actually.  Stay tuned....Should be able to respond later today.

On Thu, Sep 20, 2012 at 8:13 AM, Simon Stewart <simon.m...@gmail.com> wrote:

--

[Paul Grandjean]

Well this is great that there's so many who want to be involved with the docs!  Again, the main point of my starting this thread here is to pass along the torch.  First, I'll respond to the various questions, etc.

Mostly it requires someone who can a) be a central point of communication b) set the vision and direction for the docs c) serve as editor to clean up and vet submittals and to vet submittals.  

I agree with Luke's comment about not liking titles, especially in volunteer group like ours, but it does take someone to be the 'point-person' to lead the vision and direction.  My opinion I guess, but it worked for us on Selenium 1.0.

From what you guys have said, it seems that Luke and possibly Peter are in the best position to do this.  Do you guys just want to take it?  Should we vote?

And thanks to the rest of you who volunteered to chip in!

[Paul Grandjean]

And I want to answer some of the questions and comments you guys brought up...

@ Richard - There's already a lot of examples but most are in Java.  Many have asked for more examples.  Ideally examples would be in all 4 supported languages.  There's almost no examples for Python and Ruby.

@ Santi - Awhile back I edited the introductory chapter to emphasize WebDriver and to not encourage the IDE.  For beginners totally new to Selenium this would work.  This approach would work well for a hardcopy book but for on-line docs I think not so much since many folks would not read sequentially.  So yeah, a restructuring would be a good idea.  I'd recommend not taking out the 'total beginner' stuff though since it provides a lot of background and history that I believe folks coming from say a QTP background or, folks totally new to automation, would find helpful.

@ Adam - I agree with your suggested improvements.  Moving the IDE to a much later chapter (currently it's chapter 2) would be a very easy one with a big impact.  I should have added you to my last note, either Luke or yourself could coordinate this if you're up for it.

@ Peter - yes a few hours a week should do it.  When we did the current docs and were in the thick of writing, I'd sometimes work all day on it.  I don't think this effort would take that much very often though.  It does need continuity.  That is, the same group of committed people focusing on it for at least a good few months.

@ Pradeep, Jonathan, Kenny.  Thanks for volunteering to help!  Please be aware what is probably needed is a few folks to commit some time over a few months (or more?).  The continuity and the sense of vision is important.  I say this because I've had a lot of well-meaning folks volunteer but then nothing really came from them once they realized it's a time commitment.  I've had others send code examples thinking it helps with the docs but they don't send don't send supporting text or any thoughts about how it would integrate with the existing docs.  I don't want to dissuade you at all--just want you to know what's involved ;-)

thanks much guys for stepping up on this.  It'll be a great relief to me knowing that someone else is moving the docs forward.  I hope to help with the docs in the future when my time allows.  For now, though, I've said a lot and now I'll step back.....So who wants it?

Paul

--
 
 

[Paul Grandjean]

whoops, almost forgot.  Please though count me in for contributing to the Sel-Grid chapter.  I promised Keven Menard I'd do this and I intend to keep that promise.  I've got tons of notes that I think will be helpful.  This will be my doc-contribution over the fall and for 2013.

Paul

[Simon Stewart]

Thanks Paul! And everyone else :)

Can't wait to see the docs get their reboot!

Simon

> --
>
>

[Mike Riley]

I would be willing to help with some of it as well.  I am busy right now, since we have a show coming up, but I should be able to put in a few hours a week once we are past that.  I definitely have a bit more time at this new position.

Mike

[Jonathan Aibel]

I'm ready to dedicate some time to the documentation, given some direction.  The most obvious contribution I can make is in translating Java examples to python, but I'd be happy to do more extensive work.  Writing text doesn't scare me :-)

[Kenny Chua]

@paul no problems here with a longer term commitment to the selenium project.. I work with it a lot and am keen to give back

[Manoj K]

I would like to be a part of Documentation team. Please count me In as well.

I am using  Selenium for past 3 years and would like to do something back.

Regards,

Manoj

http://assertselenium.com

[Paul Grandjean]

Hey folks, so can someone tell me what's happening with the docs?  I'd like to remain in the loop still.

Paul

--
 
 

[Leo Laskin]

Paul,
I think Luke is taking over as doc czar.  I've personally promised him to get some ruby docs done while I am on the flight to/from Mexico...

--L

--
 
 

[Luke Inman-Semerau]

So far all that has happend is a move from Openqa.org to google appengine (still in progress of transition). Xserve / Bamboo is no longer being used to deploy the site, a new Jenkins job has been created to do that (today):

http://ci.seleniumhq.org:8080/job/SeleniumHQ/

We have some last steps still needed to complete the transition (related to DNS ~ which I believe Simon is taking care of).

The site on appengine can currently be viewed here:

http://sehq-docs.appspot.com/

Other than that I haven't seen / heard anyone else attempting anything. There are certainly many things I'd like to attempt, especially making it easier for people to contribute to the site (like a wiki interface or something else) but I haven't thought it completely through yet :) (working on a few other things).

-Luke

--
 
 

[Paul Grandjean]

Ok, great.  Thanks much Luke for stepping in.  And thanks to others for filling me in.

Would it be best to wait for the infrastructure to settle down before adding anything myself?  (No worries tho, as I'm involved in another project at the moment.)

Paul

--
 
 

[Luke Inman-Semerau]

I don't think there's any reason to wait right now. It's currently auto building to the new destination. (Literally just down to DNS switching). So if you have anything, feel free! :)

--
 
 

[Paul Grandjean]

aha, got it.  Thanks Luke!

P.S.  will you be at next year's conference?  I'm planning on attending the next one.  Would be great to meet you.

--
 
 

[Luke Inman-Semerau]

I'm certainly hoping / planning on it!

--
 
 

[Manoj K]

Luke, please let me know on where and how to get started. I guess the new location is ready. Its really good to see in Action the "Donate feature" wish to get more donations :)

[Luke Inman-Semerau]

Hi Manoj, Here's a documentation getting involved / getting started wiki page:

http://code.google.com/p/selenium/wiki/Documentation

Thanks for any contributions to the docs!

-Luke

--
 
 

[Paul Grandjean]

awesome!

--
 
 

[Manoj K]

Thanks Luke. I know this link and already have signed the SLA and also Checked out the code. 

So is there any chat room for the documentation team to Sync up so that we may talk each other and get to know what topics are being developed inorder to avoid redundancy.

Regards,

Manoj

[Leo Laskin]

We are usually in #selenium on freenode irc servers.

--
 
 

[Aarati Brahme]

Hi ,

I would like to contribute to the docs. I can help with the ruby examples. Will need some direction to get started.

Thanks,
Aarati

--
 
 

[Manoj K]

Luke,

I have sent an email to you. Please check and rever back to me.

Regards,

Manoj

[Luke Inman-Semerau]

Hi Manoj,

I think often ways people get started is to 'scratch their own itch' if there's something you see that needs to be updated, feel free to take a stab and send in a patch.

If you'd like to start tackling some of the issues on the issues list, here's all the 'docs' related ones:

http://code.google.com/p/selenium/issues/list?can=2&q=Component%3DDocs

Otherwise I don't know of any formal effort to work on 'new' items. I know some people want to add more Ruby docs / examples to the site.

I do want to convert the docs to a mainly wiki based format, but I need to collect some thoughts on what our needs will be and then find a best fit wiki software package I can plug in.

Other than that, make sure you've gone through http://code.google.com/p/selenium/wiki/Documentation and you've run the sehq site locally so you can test your changes.

Feel free to post back to the dev list when you have a patch (and please attach the patch to an issue).

Thanks for your interest in contributing!

-Luke

--
 
 

[Manoj K]

Thanks Luke.