Open Stack

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)
   - *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 to
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 around will 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? *

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?

Thank you all for reading this up to the end, and for any feedback on the
matter!

Olga.



On Thu, May 28, 2015 at 10:03 PM, Jeremy Stanley <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
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
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/9987ae6a/attachment-0001.html>