Re: [openstack-dev] Easing contributions to central documentation

[Olga Gusarenko]

On Tue, May 10, 2016 at 12:40 AM, Matt Kassawara <mkassaw...@gmail.com>
wrote:

> At each summit, I speak with a variety of developers from different
> projects about the apparent lack of contributions to the central
> documentation. At previous summits, the most common complaint involved
> using DocBook. After converting most of the documentation to RST, the most
> common complaint at the recent summit involves the review process,
> particularly the lengthy amount of time patches sit in the review queue
> with -1s for various "conventions" problems such as structure, formatting,
> grammar, spelling, etc. Unlike most OpenStack developers that focus on a
> particular project, the documentation team covers all projects and lacks
> the capacity to understand each one enough to contribute and maintain
> technically accurate documentation in a timely manner. However, covering
> all projects enables the documentation team to organize and present the
> documentation to various audiences, primarily operators and users, that
> consume OpenStack as a coherent product. In other words, the entire process
> relies on developers contributing to the central documentation. So, before
> developer frustrations drive some or all projects to move their
> documentation in-tree which which negatively impacts the goal of presenting
> a coherent product, I suggest establishing an agreement between developers
> and the documentation team regarding the review process.
>
> As much as the documentation team wants to present OpenStack as a coherent
> product, it contains many projects with different contribution processes.
> In some cases, individual developers prefer to contribute in unique ways.
> Thus, the conventional "one-size-fits-all" approach that the documentation
> team historically takes with reviewing contributions from developers yields
> various levels of frustration among projects and developers. I ran a
> potential solution by various developers during the recent summit and
> received enough positive feedback to discuss it with a larger audience. So,
> here goes...
>
> A project or individual developer decides the level of documentation team
> involvement with reviewing patches. The developer adds a WIP to the
> documentation patch while adding content to prevent premature reviews by
> the documentation team. Once the content achieves a sufficient level of
> technical accuracy, the developer removes the WIP and adds a comment in the
> review indicating of the following preferences:
>
> 1) The documentation team should review the patch for compliance with
> conventions (proper structure, format, grammar, spelling, etc.) and provide
> feedback to the developer who updates the patch.
> 2) The documentation team should modify the patch to make it compliant and
> ask the developer for a final review to prior to merging it.
> 3) The documentation team should only modify the patch to make it build
> (if necessary) and quickly merge it with a documentation bug to resolve any
> compliance problems in a future patch by the documentation team.
>
> What do you think?
>

+1 to the second option!

In most cases it's faster and easier just to patch your suggestions rather
than comment -> wait for the response -> check again. Just less talk, more
action...

Olga


>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Best regards,
Olga Gusarenko

Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv, Ukraine
ogusare...@mirantis.com | skype: gusarenko.olga
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [Fuel] [Fuel UI] UI text guidelines

[Olga Gusarenko]

Good Friday to everyone!

This is just to inform you that UI text guidelines are now available in the
Contributor Guide:

http://docs.openstack.org/contributor-guide/ui-text-guidelines.html

This will be interesting for designers and developers, as well as
reviewers, who works on OpenStack user interfaces. Please follow these
recommendations to ensure UI usability and consistency.

Special thanks to Linette Williams and Gudrun Wolfgram for working on this!

-- 
Best regards,
Olga Gusarenko

Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv, Ukraine
ogusare...@mirantis.com | skype: gusarenko.olga
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [fuel] Nominate Svetlana Karslioglu for fuel-docs core

[Olga Gusarenko]

+1
Svetlana, thank you for your contribution, and looking forward to working
with you on the Fuel documentation improvement!

Best,
Olga

On Thu, Oct 8, 2015 at 11:13 AM, Alexander Adamov 
wrote:

> +1 to Svetlana's nomination.
>
> On Tue, Sep 29, 2015 at 4:58 AM, Dmitry Borodaenko <
> dborodae...@mirantis.com> wrote:
>
>> I'd like to nominate Svetlana Karslioglu as a core reviewer for the
>> fuel-docs-core team. During the last few months, Svetlana restructured
>> the Fuel QuickStart Guide, fixed a few documentation bugs for Fuel 7.0,
>> and improved the quality of the Fuel documentation through reviews.
>>
>> I believe it's time to grant her core reviewer rights in the fuel-docs
>> repository.
>>
>> Svetlana's contribution to fuel-docs:
>>
>> http://stackalytics.com/?user_id=skarslioglu=all_type=all=fuel-docs
>>
>> Core reviewer approval process definition:
>> https://wiki.openstack.org/wiki/Governance/Approved/CoreDevProcess
>>
>> --
>> Dmitry Borodaenko
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Best regards,
Olga

Technical Writer
skype: gusarenko.olga
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [Fuel] Nominate Alexander Adamov and Olena Logvinova for fuel-docs cores

[Olga Gusarenko]

Dear Fuelers,

I would like to nominate Alexander Adamov and Olena Logvinova for the
fuel-docs-core status:

http://stackalytics.com/?user_id=aadamov=all_type=all=fuel-docs
http://stackalytics.com/?user_id=ologvinova=all_type=all=fuel-docs

They are making a great contribution into Fuel documentation as
professional technical writers. And it is high time to grant them core
reviewer's rights within fuel-docs.

Core reviewer approval process definition:
https://wiki.openstack.org/wiki/Governance/Approved/CoreDevProcess

-- 
Best regards,
Olga

Technical Writer
skype: gusarenko.olga
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev