[all] Removing privacy breaches in doc

Dmitry Tantsur dtantsur at redhat.com
Wed Apr 10 12:42:26 UTC 2019


On 4/10/19 2:26 PM, Sean Mooney wrote:
> On Tue, 2019-04-09 at 18:46 +0200, Dmitry Tantsur wrote:
>> On 4/8/19 8:13 PM, Sean McGinnis wrote:
>>>>>>
>>>>>> The rendering on PyPi, and the validation that they do that will reject the
>>>>>> package upload if it has README syntax errors, is not aware of any Sphinx
>>>>>> extensions we use in our normal docs, so pulling in other documentation into
>>>>>> the README could potentially cause release issues.
>>>>>
>>>>> Good point. Maybe we should just stop including README content in sphinx
>>>>> docs, and not do anything additional that's more complex?
>>>>>
>>>>
>>>> Honestly, this means copy-paste and that one of the copies will probably get
>>>> outdated.
>>>>
>>>
>>> What is in the README that is needed in the documentation? For me, those have
>>> always been entirely different audiences and therefore different content.
>>
>> I don't think it's any different. Both README and the index page serve as an
>> introduction to the project. The same people will land at one of them, depending
>> if they come from github/gitea or from docs.o.o
> you assume that devs read docs.o.o

Well, I personally do read them all the time..

> i personally much prefer reading the rst then the renderd html content
> so i think they do have slight different auidence in that respect even if they have
> the same contet.

I think the audience will see whatever the search engine will lead them to. 
https://duckduckgo.com/?q=openstack+nova gives me 1. docs.o.o, 2. wiki, 3. 
github. Chances are very high I would check the docs rather then the source code 
first.

> 
> i could happily live in a world wehre docs.o.o was not a thing but if the RSTs ever
> got to a point where they were not readable without sphinx due to tomany uses
> of include then that woudl be an issue for me.
>>
>>>
>>> Maybe it just needs a different perspective for these project from how they've
>>> used them so far?
>>>
>>
>>
> 




More information about the openstack-discuss mailing list