Open Stack

Both situations. For the installation guide, we really don't want people
finding and/or installing defunct releases because most new users don't
understand the release cycle nor do we fix bugs in documentation for those
releases. Filename changes impact all guides, regardless of version. If we
rename a file, the old file becomes frozen in time, yet Google still finds
it... often before the new file.

On Fri, Jun 17, 2016 at 9:24 AM, Anne Gentle <annegentle at justwriteclick.com>
wrote:

>
>
> On Fri, Jun 17, 2016 at 10:19 AM, Matt Kassawara <mkassawara at gmail.com>
> wrote:
>
>> Anne,
>>
>> I think we do a fairly good job of removing links to defunct
>> documentation from d.o.o. However, we don't necessarily know what Google
>> shows to people when they search for documentation, hence why we should
>> probably make an effort to perform a general audit and remove files
>> involving defunct documentation, particularly the installation guides.
>>
>
> By defunct, do you mean:
> Is no longer accurate for the current release? For example, the liberty
> install guide files are still accurate for installing liberty, so those
> files should remain.
>
> or
>
> Is not intended to be read by anyone for any reason? For example, when a
> file name changes and the file remains indexed by Google but is not part of
> the intended deliverable.
>
> An audit would be fine, as long as we know the parameters for the audit's
> accuracy.
> Anne
>
>
>>
>> On Fri, Jun 17, 2016 at 7:18 AM, Anne Gentle <
>> annegentle at justwriteclick.com> wrote:
>>
>>>
>>>
>>> On Fri, Jun 17, 2016 at 4:16 AM, Pranav Salunke <dguitarbite at gmail.com>
>>> wrote:
>>>
>>>> Hello,
>>>>
>>>> Thanks for acknowledging and identifying this issue. Check my in-line
>>>> comments.
>>>>
>>>> One of our larger problems is that people just use Google, and Google
>>>>> loves to rank our old (often unlinked on d.o.o) content higher than new
>>>>> content because we can't effectively delete files. Without knowledge of
>>>>> release naming/cycle and the latest version, people often stumble upon
>>>>> older documentation that is either irrelevant or of questionable quality.
>>>>> For example, compare the installation guide for Juno with the installation
>>>>> guide for Mitaka.
>>>>>
>>>>
>>>> This is one of the bigger issues, apart from having confusion (from
>>>> google's search results!) to linking to outdated documentation.
>>>>
>>>
>>> When you see this it should be reported as a bug. Until we have improved
>>> docs publishing with
>>> http://specs.openstack.org/openstack-infra/infra-specs/specs/doc-publishing.html
>>> the fix is a manual one, so a bug must be reported in order to fix the
>>> links to outdated documentation.
>>>
>>>
>>>> Other aspect is that people want and like to use the official upstream
>>>> documentation but there are other webpages which sneak in and kind of just
>>>> mess around with the awesome updated documentation that we provide.
>>>>
>>>
>>> Can you say more about this? The words "sneak" and "mess" sound like
>>> there's a deeper issue that we'll need more specifics if we want to fix it.
>>>
>>>
>>>> I agree with Matt and add this other aspect which is confusing.
>>>> Deliberately not naming the other non-upstream sources of documentation.
>>>>
>>>
>>> Are you not naming the sources, or are you saying we don't name the
>>> sources and it would be useful to do so?
>>>
>>> Anne
>>>
>>>
>>>>
>>>>
>>>>> Thanks for sending this, I really appreciate all the kind words you
>>>>>> have for the project!
>>>>>>
>>>>>
>>>> Lana,
>>>>
>>>> Welcome :). I am a part of this team, so I fell entitled to bring up
>>>> things to improve our teams efforts.
>>>>
>>>> As far as 'extra' efforts, I do try to get involved as much as
>>>>>> possible, but there's always more that can be done (and by people who are
>>>>>> not me!). I'm considering putting in a documentation talk for Barcelona,
>>>>>> which I haven't done since becoming PTL, and I'm also spending a lot of
>>>>>> time talking to our CPLs to ensure we have project visibility. The What's
>>>>>> Up, Doc newsletter is also my way of getting our message out to other
>>>>>> groups.
>>>>>>
>>>>>
>>>> Lana, I agree, we should have a few talks showcasing the documentation
>>>> team's efforts. Some internal team and process discussions, explaining the
>>>> development models and also giving a high level overview of the
>>>> docs.openstack.org. Most often people are confused about the scope of
>>>> different books esp. I have heard a lot of confusion about Admin, Ops and
>>>> Architecture guides. I guess we could really solve this issue through your
>>>> talks at the summit.
>>>>
>>>> What's Up Doc newsletter is awesome but it is confined to improve
>>>> cross-communication in the OpenStack community. I think its really
>>>> important to do this but this does not address new comers and googlers!
>>>> Note: Not every end-user for manuals reads the ML's!
>>>>
>>>> I'm always up for new ideas, though :)
>>>>>
>>>>>
>>>> Kind of falling short of ideas here, but I am sure the community would
>>>> come up with good creative ideas here.
>>>>
>>>> Regards,
>>>> Pranav
>>>>
>>>>
>>>> _______________________________________________
>>>> OpenStack-docs mailing list
>>>> OpenStack-docs at lists.openstack.org
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>>
>>>>
>>>
>>>
>>> --
>>> Anne Gentle
>>> www.justwriteclick.com
>>>
>>
>>
>
>
> --
> Anne Gentle
> www.justwriteclick.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160617/c12bcddd/attachment-0001.html>