Open Stack

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.

>   * /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.

> 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.

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