fuel-dev team mailing list archive

[Andrew Woodward <xarses@xxxxxxxxx>]

I've recently worked with etherpad for some other openstack items and
feel that it is likely a better candidate than google-docs, wiki, and
git.

Comments; Etherpad, while having no sidebar comments forces each
contributor to edit in their own color, the color is tracked and the
editor can set their name or remain anonymous, like using the wiki
comments are tracked inline but since the editor has a color, their
change is more visible.

Tracking changes; Etherpad has a time-slider (click the clock on the
upper right) that is similar to the diff slider github offers for
images. This allows you to replay the changes or to move between
bookmarked positions (the star button next to the clock) that allow
for the editors to mark a specific document revision.

Permissions; Unlike git which would require some permissions agent and
be a burden to contributors, etherpad doesn't have any permissions to
mess with, similar to an open google doc, or wiki page.

Andrew
Mirantis

On Mon, Nov 11, 2013 at 10:55 AM, Dmitry Borodaenko
<dborodaenko@xxxxxxxxxxxx> wrote:
> I agree, tracking revision history for design documents is important,
> and having RST in a Git repo is the best way to achieve that.
>
> Maybe we can add a design section to the fuel-docs repo, and agree
> that once the design is finalized (which typically would be after
> implementation has started but before it's completed) it should be
> moved from Google Drive to Git? That way, we can have a fast and
> efficient discussion of design while it's still being changed rapidly,
> and we end up with a design document that we can easily reference and
> reuse from our documentation site once design is more or less
> completed.
>
> On Mon, Nov 11, 2013 at 3:03 AM, Bogdan Dobrelya <bdobrelia@xxxxxxxxxxxx> wrote:
>> On 11/11/2013 12:19 PM, Mike Scherbakov wrote:
>>
>> Fuel folks,
>> if you use google documents and put your design for any enhancement there,
>> we need to make sure such documents are never lost in order to avoid
>> duplication of work.
>>
>> Find or create corresponding blueprint on launchpad
>>
>> Make sure it has good description (issue statement, main idea on how it is
>> going to be addressed)
>> Blueprint has reference link to the google doc with design
>>
>> Make sure your GoogleDoc has following permissions:
>>
>> Anyone can comment
>> Core team can edit
>>
>> I would prefer to use wiki where possible, and actually use google docs at
>> the phase when a lot of collaboration is needed (google docs have great
>> comments feature).
>>
>> Thank you,
>> --
>> Mike Scherbakov
>>
>>
>> I believe we have to consider the cases for design docs are being updated
>> while implementation is in progress:
>>
>> - How we can track the 'new changes' vs 'done'?
>>
>> I suggest we have to use some tools for github (and/or gerrit) integration
>> with our design docs, thus docs should be kept in any "diffable" way (f.e.
>> in RST format?), so we can issue git diff against any design docs any time
>> to see what has been changed since the last commits, as well to address them
>> in implementation related activities.
>>
>> F.e. the history of design and implementation could look like this:
>>
>> docs:
>> 54900c8 - Bogdan Dobrelya, 32 minutes ago : Update the structure format for
>> astute.yaml for feature1
>> 11ec45b - Vladimir Kuklin, 5 days ago : Create the structure format for
>> astute.yaml for feature1
>>
>> Implementation (topic branch):
>> fe1a2a0 - Vladimir Kuklin, 10 minutes ago : Implement 54900c8 of feature1
>> design
>> 491382d - Sergey Vasilenko, 4 days ago : Implement 11ec45b of feature1
>> design
>>
>> I believe the active collaboration always suggests active changes in design,
>> but development/fix process have a tendency to start at the very early
>> stages of design and never stops as well ... Thats why, IMHO, it is critical
>> to track design docs changes appropriately.
>>
>> --
>> Best regards,
>> Bogdan Dobrelya,
>> Researcher TechLead, Mirantis, Inc.
>> +38 (066) 051 07 53
>> Skype bogdando_at_yahoo.com
>> 38, Lenina ave.
>> Kharkov, Ukraine
>> www.mirantis.com
>> www.mirantis.ru
>> bdobrelia@xxxxxxxxxxxx
>>
>>
>> --
>> Mailing list: https://launchpad.net/~fuel-dev
>> Post to     : fuel-dev@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fuel-dev
>> More help   : https://help.launchpad.net/ListHelp
>>
>
>
>
> --
> Dmitry Borodaenko
>
> --
> Mailing list: https://launchpad.net/~fuel-dev
> Post to     : fuel-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fuel-dev
> More help   : https://help.launchpad.net/ListHelp



-- 
If google has done it, Google did it right!