forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: Writing our guidelines by use-cases
Date Tue, 20 Jul 2004 11:12:54 GMT
Sean Wheller wrote:
> Thorsten Scherler wrote:
> > I now can understand better that e.g. documentation
> > can always go into SVN seeing that other committer will pick it up and
> > helping to fix it. This committer would not be able to help if the
> > document is still *only* on my local harddrive.
> 
> While I am not contributing to the project, I do contribute to other projects.

Discussion is a contribution around here. Welcome.

> As a documentation contributor to Open Source projects, I can say that the 
> best thing you can do is to commit your work. It's of no use to anyone when 
> it is sitting on your hard drive.
> 
> Do small parts of the document, say section at a time, then commit. This will  
> enable others to help you and will speed progress of the total documentation 
> development. Before you go hacking away, try to get an outline and commit 
> just that. Explain where the document will fit into the greater picture of 
> the projects documentation (don't duplicate). Then discuss it with members.
> 
> If they make changes or additions it will be good since they have shown that 
> they are taking interest and share ownership of the documents development. 
> Generally you will find that specific people will talk to you about only the 
> parts they are working on or for which they could be considered a subject 
> matter expert. This is good. Since once you know who the SME is you can save 
> time by speaking to the person only on that point.

Yes. The difference here is that we attempt to do all
discussion on the mailing list and try not to do private
off-list discussion. Being on the list, everyone can listen
and learn and hopefully contribute.

> They will also save time 
> as they don't need to check the whole document, only that which is important 
> to their area. In big projects it is also helpful if you modularize your 
> source so that people can work on specific parts without adding confusion and 
> having to resolve conflicts all the time.

Hah, we would love to have congestion in the documentation
contributions. 

> Once this is done, then select sections you will be working on. Try to work on 
> sections that others are not working on.

On large documentation tasks we will control that through our
Issue tracker.

> Again, work small, commit often. If 
> you modularize then you can generally work on a sect in one module, commit 
> and wait for response while working on a section of another module. So 
> allowing people time to collaborate.

Yes that is very powerful.

> If you are not sure what to do with 
> regard to committing patches then ask one of the devs if you can send them 
> the patch to review and and commit.

Patches should always be added to the issue tracker so that
no-one needs to pass stuff around behind-the-scenes.
Any developer or committer can investigate it.

This is what sparked this conversation. We do the
"commit-then-review" method around here.

> I am assuming you already know how to 
> diff and create patches against the repository. If not let me know offlist 
> and I will help.

Actually there is an old howto in either Forrest or Cocoon that
we need to resurrect.

> Hope this helps.

Yes, thanks.

-- 
David Crossley


Mime
View raw message