directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ole Ersoy <ole.er...@gmail.com>
Subject Re: [Site]
Date Mon, 19 Mar 2007 17:05:09 GMT
Hey Ersin, Emmanuel,

I love the idea of having users be able to add comments directly into 
the documentation.

I also like having professional looking "Uncommmented and 
clean/finalized" documentation like the site now has.

So from a process perspective it sounds like we are thinking that there 
is a "Work in progress" documentation
area, that feeds into a review queue, where whoever is responsible for 
that page/pages
reviews the commit and patches the corresponding site documentation.

This should be really simple like a link arrives in email per the 
comment to the review.  The reviewer clicks
on the link, reviews, makes a few adjustments maybe, and then pushes 
another button, and the main site is updated.

I also think the person who made the comment on a documentation page 
should get an email
saying that the comment has been incorporated.  That way they know where 
to look for their comment
in the future in case they need it.

I also think that the user should have an account, and that the system 
updates the users account "bookmarks" with the edit they committed.

Summary:
User: Provides comment (Via a button on the main finalized documentation 
page that opens commenting editor)
System: Generates comment patch and sends to reviewer (Bugzilla type 
patch review display)
Reviewer: Reviews and changes stuff (or just just clicks ok)
System: Updates main site
System: Sends email to user about commit to main documentation (And 
updates bookmarks - just to add a little sugar on top :-)   )

Cheers,
- Ole



Ersin Er wrote:
> On 3/19/07, Emmanuel Lecharny <elecharny@gmail.com> wrote:
>> Hi guys,
>>
>> I guess this mail is much more targeting Ersin, but may be someone 
>> lese can
>> help.
>>
>> Justen Stepka, from Atlassian (ya know, the company which product are 
>> just,
>> well, incredibly cool) has suggested that we should allow users to add
>> comments on the site's pages. This is just smart. Now, the question 
>> is : how
>> do we do that ?
>
> This is not a new idea. We cannot do that (well under some conditions
> may be possible). Because, the site content is actually the
> documentation and it's (or it'll be) distributed with the released
> products. Components of the released products should all be committed
> (or contributed) by people who signed the appropriate Apache license.
>
> This is stated at http://cwiki.apache.org/CWIKI as:
>
> "Some Spaces are being used to create the Project documentation.
> Editing access to such Spaces might be restricted to Project
> committers or individuals who have filed a Contributor's License
> Agreement with the ASF."
>
>> We currently have this little grey icon on the right top of each 
>> page, it
>> would be a good idea to add another icon for comments, but more 
>> visible. And
>> also the same icon at the end of each page. I guess the template must be
>> changed. The comments should not be shown entirely on the resultant 
>> page,
>> but folded, to avoid having giant pages.
>>
>> If we have those little 'comment' icons on our page will help a lot to
>> improve the site : we are 80% not english natives, so the text in those
>> pages migth be seen as pidgin to english natives.
>
> We may allow comments, but we should remove them when distributing the
> documentation.
>
>> wdyt ?
>
> Of course we should decide on an appropriate solution but it's not 
> that obvious.
>
>> -- 
>> Cordialement,
>> Emmanuel L├ęcharny
>> www.iktek.com
>
>


Mime
View raw message