Open Stack

Thanks Andreas and Bernd for responds!

Please, see my comments inlines.


On Wed, Jul 1, 2015 at 11:56 AM, Andreas Jaeger <aj at suse.com> wrote:

> On 07/01/2015 10:33 AM, Olga Gusarenko wrote:
>
>> Hi to everyone!
>>
>> I am rising this thread again because I am willing to be involved in the
>> matter if the community decides in favour of the proposed change, cause
>> I am strongly convinced that it can improve the doc contributors'
>> experience. Lets finally dot all the 'i's =)
>>
>> I have already discussed the matter with Lana, took into consideration
>> your opinions (you have kindly mailed in this thread), and here is what
>> I came up with.
>>
>> *Problem Description*
>>
>> Basing on my own experience and the experience of my colleagues, the
>> information for the docs contributors located on wiki sometimes contains
>> outdated info and can be improved by restructuring.
>>
>> *Proposed Solution*
>>
>> We propose to initiate the creation of the Documentation Contributors
>> Guide targeted at the contributors to the OpenStack documentation that
>> will cover the following issues:
>>
>>   * Markup conventions
>>   * Terminology and writing syntax conventions
>>   * Screenshots and topologies conventions
>>   * Documentation structure
>>   * Gerrit workflow (HowTo)
>>
>
> The gerrit workflow should really be part of the infra-manual. Let's avoid
> duplication with that one.
>


If we put the gerrit workflow to some other place (different from another
content location), the remaining information will fit the "Style Guide"
name.
And I am against it as it is not convenient for me as for a contributor to
refer to different locations while making changing in the docs. I am for a
single entry for all the contribution-related staff.



>
>    * /anything else interesting to the community /
>>
>> *What To Be Done*
>>
>> This task can be resolved in two steps:
>>
>> /_STEP 1:_/ moving the cleaned up content from wiki.
>>
>> As we are treating our documentation as the code and willing others to
>> do so, we propose to relocate all the conventions, how to instructions
>> and any docs contributor-related things to 'somewhere'. probably
>> tohttp://docs.openstack.org/infra <http://docs.openstack.org/infra> (as
>> this was proposed earlier by Christian) as a single-entry, full, and
>> neatly organized guide that answers questions that arise in the docs
>> creation workflow.
>>
>  The wiki is definitely not much convenient, it has narrowed
>> functionality and lacks a number of features that have become essential
>> part of any internet user nowadays, such as search, proper navigation,
>> and some others.
>>
>> Moving things aroundwill noways influence its openness to the community
>> or make the conventions less flexible. This will only unify and simplify
>> the process. Besides, the docs contributor guide should be definitely
>> treated more seriously by the contributors than things placed in wiki.
>>
>> /_STEP 2:_/ discuss and add the content that's missing from the
>> 'I-am-a-contributor' position.
>>
>> *Problems to Discuss*
>>
>> Lets answer the main questions and plan the future basing on the
>> decision made:
>>
>> 1. The first and the most important question is:
>>
>> *Documentation Contributor Guide: to be or not to be? *
>>
>
> I'd love to see this - but only as long as there's a small team dedicated
> to move everything from the wiki.
>
> I also like to see a spec for this effort to design what we want.
>


I am willing to take care of this after we discuss and arrive at a
consensus about the guide scopes, creating/publishing procedure and
deadlines.



>
>  2. Where is the most appropriate location for it?
>>
>> I agree that http://docs.openstack.org/infra is the best place, but
>> before taking any steps in this direction, we should thoroughly discuss
>> what kind of content this should include with the its owner, and find a
>> compromise. Jeremy, did I understand your point right?
>>
>
> We can easily publish anywhere where it fits, the URL is for me just
> cosmetics. I don't think that /infra is the best fit.
>
> Looking at your question, the question becomes more: Do we move some parts
> to infra-manual (docs.openstack.org/infra/manual) and some to our own
> place and link between the two? Or what's the relationship between what you
> propose and infra-manual.
>


No, I am against splitting the contributor-related information. I am for
the Contributor Guide (not a kind of a guide related to the writing style
only).
If you know the better place for it, lets discuss as I am probably not
experienced enough in this question.



>
> Do we want to do this work as part of an existing repository - docs-specs
> and openstack-manuals come to mind for that - or create a new one?
>
>
>> Thank you all for reading this up to the end, and for any feedback on
>> the matter!
>>
>
> Thanks, Olga for moving this forward!
>
> Andreas
>
>  Olga.
>>
>>
>>
>> On Thu, May 28, 2015 at 10:03 PM, Jeremy Stanley <fungi at yuggoth.org
>> <mailto:fungi at yuggoth.org>> wrote:
>>
>>     On 2015-05-28 19:24:15 +0200 (+0200), Christian Berendt wrote:
>>     [...]
>>     > If we confirm to move the content into the already existing
>>     > developers guide what do we have to do to proceed?
>>
>>     Seems like a great idea for anything that's a fit. Just keep in mind
>>     that we want to keep infra-manual focused on topics that are
>>     relevant to community infrastructure interactions for the majority
>>     of project-teams in our ecosystem, and not drill down into workflow
>>     recommendations which only apply to some specific projects. For one
>>     thing, the Infra team doesn't want to become a review bottleneck for
>>     individual project-team documents.
>>
>>     > I think we have to write a spec for docs-specs and I think we
>>     > should discuss this topic with the owner of the developers guide
>>     > (openstack-infra mailinglist?).
>>
>>     I'm happy to respond here, but yes you might reach more of the
>>     infra-manual authors on the -dev or -infra MLs.
>>     --
>>     Jeremy Stanley
>>
>>     _______________________________________________
>>     OpenStack-docs mailing list
>>     OpenStack-docs at lists.openstack.org
>>     <mailto:OpenStack-docs at lists.openstack.org>
>>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>>
>>
>> --
>> Best regards,
>> Olga
>>
>> Technical Writer
>> skype: gusarenko.olga
>>
>>
>>
>> _______________________________________________
>> OpenStack-docs mailing list
>> OpenStack-docs at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
>        HRB 21284 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>


-- 
Best regards,
Olga

Technical Writer
skype: gusarenko.olga
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150701/bc5450b6/attachment.html>