Open Stack

1. The first and the most important question is:

Documentation Contributor Guide: to be or not to be? 

YES! 
By an occasional contributor who still often wonders what’s the right procedure.

2. Where is the most appropriate location for it?

 

I don’t mind, but I agree that the Wiki pages are or have become hard to read.

 

From: Olga Gusarenko [mailto:ogusarenko at mirantis.com] 
Sent: Wednesday, July 01, 2015 5:33 PM
To: openstack-docs
Subject: Re: [OpenStack-docs] move of documentation-related wiki content (was: Re: Wrapup - Liberty Design Summit)

 

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

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150701/4e4fe0cc/attachment.html>