[OpenStack-docs] [openstack-docs] Visibility of docs.openstack.org in the internet

Anne Gentle annegentle at justwriteclick.com
Fri Jun 17 15:24:10 UTC 2016


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/95bf0bce/attachment.html>


More information about the OpenStack-docs mailing list