Re: [openstack-dev] Adding "not docs" banner to specs website?

[Doug Hellmann]

Excerpts from Rochelle Grober's message of 2018-03-22 01:05:42 +:

> It could be *really* useful if you could include the date (month/year
> would be good enough)of the last significant patch (not including
> the reformat to Openstackdocstheme).  That could give folks a great
> stick in the mud for what "past" is for the spec.  It might even
> incent some to see if there are newer, conflicting or enhancing
> specs or docs to reference.
> 
> --Eoxky

The docs theme includes this information just below the title on
each page. See https://docs.openstack.org/reno/latest/ and look for
"UPDATED" for an example.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Rochelle Grober]

It could be *really* useful if you could include the date (month/year would be 
good enough)of the last significant patch (not including the reformat to 
Openstackdocstheme).  That could give folks a great stick in the mud for what 
"past" is for the spec.  It might even incent some to see if there are newer, 
conflicting or enhancing specs or docs to reference.

--Eoxky

> 
Doug Hellmann wrote:
> 
> Excerpts from Jim Rollenhagen's message of 2018-03-19 19:06:38 +:
> > On Mon, Mar 19, 2018 at 3:46 PM, Jeremy Stanley 
> wrote:
> >
> > > On 2018-03-19 14:57:58 + (+), Jim Rollenhagen wrote:
> > > [...]
> > > > What do folks think about a banner at the top of the specs website
> > > > (or each individual spec) that points this out? I'm happy to do
> > > > the work if we agree it's a good thing to do.
> > > [...]
> > >
> > > Sounds good in principle, but the execution may take a bit of work.
> > > Specs sites are independently generated Sphinx documents stored in
> > > different repositories managed by different teams, and don't
> > > necessarily share a common theme or configuration.
> >
> >
> > Huh, I had totally thought there was a theme for the specs site that
> > most/all projects use. I may try to accomplish this anyway, but will
> > likely be more work that I thought. I'll poke around at options (small
> > sphinx plugin, etc).
> 
> We want them all to use the openstackdocstheme so you could look into
> creating a "subclass" of that one with the extra content in the header, then
> ensure all of the specs repos use it.  We would have to land a small patch to
> trigger a rebuild, but the patch switching them from oslosphinx to
> openstackdocstheme would serve for that and a small change to the readme
> or another file would do it for any that are already using the theme.
> 
> Doug
> 
> __
> 
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-
> requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Jim Rollenhagen]

>
> We want them all to use the openstackdocstheme so you could look
> into creating a "subclass" of that one with the extra content in
> the header, then ensure all of the specs repos use it.  We would
> have to land a small patch to trigger a rebuild, but the patch
> switching them from oslosphinx to openstackdocstheme would serve
> for that and a small change to the readme or another file would do it
> for any that are already using the theme.
>

Thanks Doug, I'll investigate this route more when I have some free time to
do so. :)

// jim
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Doug Hellmann]

Excerpts from Jeremy Stanley's message of 2018-03-19 20:17:37 +:
> On 2018-03-19 16:09:14 -0400 (-0400), Doug Hellmann wrote:
> [...]
> > We want them all to use the openstackdocstheme so you could look
> > into creating a "subclass" of that one with the extra content in
> > the header, then ensure all of the specs repos use it.  We would
> > have to land a small patch to trigger a rebuild, but the patch
> > switching them from oslosphinx to openstackdocstheme would serve
> > for that and a small change to the readme or another file would do it
> > for any that are already using the theme.
> 
> Seems like a reasonable incentive for some needed cleanup.

And if I wasn't clear, we would want to put that subclass in the
openstackdocstheme repo so we can easily keep the styles up to date
over time.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Jeremy Stanley]

On 2018-03-19 16:09:14 -0400 (-0400), Doug Hellmann wrote:
[...]
> We want them all to use the openstackdocstheme so you could look
> into creating a "subclass" of that one with the extra content in
> the header, then ensure all of the specs repos use it.  We would
> have to land a small patch to trigger a rebuild, but the patch
> switching them from oslosphinx to openstackdocstheme would serve
> for that and a small change to the readme or another file would do it
> for any that are already using the theme.

Seems like a reasonable incentive for some needed cleanup.
-- 
Jeremy Stanley


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Doug Hellmann]

Excerpts from Jim Rollenhagen's message of 2018-03-19 19:06:38 +:
> On Mon, Mar 19, 2018 at 3:46 PM, Jeremy Stanley  wrote:
> 
> > On 2018-03-19 14:57:58 + (+), Jim Rollenhagen wrote:
> > [...]
> > > What do folks think about a banner at the top of the specs website
> > > (or each individual spec) that points this out? I'm happy to do
> > > the work if we agree it's a good thing to do.
> > [...]
> >
> > Sounds good in principle, but the execution may take a bit of work.
> > Specs sites are independently generated Sphinx documents stored in
> > different repositories managed by different teams, and don't
> > necessarily share a common theme or configuration.
> 
> 
> Huh, I had totally thought there was a theme for the specs site that
> most/all projects use. I may try to accomplish this anyway, but will likely
> be more work that I thought. I'll poke around at options (small sphinx
> plugin, etc).

We want them all to use the openstackdocstheme so you could look
into creating a "subclass" of that one with the extra content in
the header, then ensure all of the specs repos use it.  We would
have to land a small patch to trigger a rebuild, but the patch
switching them from oslosphinx to openstackdocstheme would serve
for that and a small change to the readme or another file would do it
for any that are already using the theme.

Doug

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Jay Bryant]

Agree this  is a good idea.

Let me know what we can do to help.

Jay

On Mon, Mar 19, 2018, 9:58 AM Jim Rollenhagen 
wrote:

> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
>
> What do folks think about a banner at the top of the specs website (or
> each individual spec) that points this out? I'm happy to do the work if we
> agree it's a good thing to do. My suggested wording:
>
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."
>
> // jim
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Jeremy Stanley]

On 2018-03-19 19:06:38 + (+), Jim Rollenhagen wrote:
[...]
> Huh, I had totally thought there was a theme for the specs site
> that most/all projects use. I may try to accomplish this anyway,
> but will likely be more work that I thought. I'll poke around at
> options (small sphinx plugin, etc).
[...]

A lot of them may share the same theming, so you can probably get a
significant coverage by going that route and work up to more
complete coverage as you can convince others to switch to it. Also
they all (or at least almost all?) share the same publication job so
that's a possible alternative means of injection as well.
-- 
Jeremy Stanley


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Jim Rollenhagen]

On Mon, Mar 19, 2018 at 3:46 PM, Jeremy Stanley  wrote:

> On 2018-03-19 14:57:58 + (+), Jim Rollenhagen wrote:
> [...]
> > What do folks think about a banner at the top of the specs website
> > (or each individual spec) that points this out? I'm happy to do
> > the work if we agree it's a good thing to do.
> [...]
>
> Sounds good in principle, but the execution may take a bit of work.
> Specs sites are independently generated Sphinx documents stored in
> different repositories managed by different teams, and don't
> necessarily share a common theme or configuration.


Huh, I had totally thought there was a theme for the specs site that
most/all projects use. I may try to accomplish this anyway, but will likely
be more work that I thought. I'll poke around at options (small sphinx
plugin, etc).


> It might be
> possible to hack around this with some sort of content injection in
> Apache but that also seems like a bit of a kluge.


Totally agree. :) Thanks Jeremy!

// jim
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Jeremy Stanley]

On 2018-03-19 14:57:58 + (+), Jim Rollenhagen wrote:
[...]
> What do folks think about a banner at the top of the specs website
> (or each individual spec) that points this out? I'm happy to do
> the work if we agree it's a good thing to do.
[...]

Sounds good in principle, but the execution may take a bit of work.
Specs sites are independently generated Sphinx documents stored in
different repositories managed by different teams, and don't
necessarily share a common theme or configuration. It might be
possible to hack around this with some sort of content injection in
Apache but that also seems like a bit of a kluge.
-- 
Jeremy Stanley


signature.asc
Description: PGP signature
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Petr Kovar]

On Mon, 19 Mar 2018 14:57:58 +
Jim Rollenhagen  wrote:

> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
> 
> What do folks think about a banner at the top of the specs website (or each
> individual spec) that points this out? I'm happy to do the work if we agree
> it's a good thing to do. My suggested wording:
> 
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."

Might be a good idea to also include a pointer to
https://docs.openstack.org/.

Thanks,
pk

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Julia Kreger]

I'm all for the idea, although that may be because I've been been one
of the people in the past attempting to assist people who have found
specs, and who are are confused or frustrated. I believe it is because
some people latch on to the highly technical design documents when
they can't find $complex thing in $complex documentation easily.

-Julia

On Mon, Mar 19, 2018 at 7:57 AM, Jim Rollenhagen  
wrote:
> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
>
> What do folks think about a banner at the top of the specs website (or each
> individual spec) that points this out? I'm happy to do the work if we agree
> it's a good thing to do. My suggested wording:
>
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."
>
> // jim
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>


On Mon, Mar 19, 2018 at 7:57 AM, Jim Rollenhagen  
wrote:
> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
>
> What do folks think about a banner at the top of the specs website (or each
> individual spec) that points this out? I'm happy to do the work if we agree
> it's a good thing to do. My suggested wording:
>
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."
>
> // jim
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Sean McGinnis]

On Mon, Mar 19, 2018 at 02:57:58PM +, Jim Rollenhagen wrote:
> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
> 
> What do folks think about a banner at the top of the specs website (or each
> individual spec) that points this out? I'm happy to do the work if we agree
> it's a good thing to do. My suggested wording:
> 
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."
> 
> // jim

I like that idea. There have been several times where this has caused
confusion. If there was some sort of notification on the page, that may make it
more likely that random web search readers will understand that they are not
reading "official" documentation.


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Adding "not docs" banner to specs website?

[Amy Marrich]

I think it's a good idea especially as some times a spec is never completed
or not in the same release.

Thanks,

Amy(spotz)

On Mon, Mar 19, 2018 at 9:57 AM, Jim Rollenhagen 
wrote:

> Ironic (and surely other projects) have had to point out many times that
> specs are a point in time design discussion, and not completed
> documentation. It's obviously too much work to go back and update specs
> constantly.
>
> What do folks think about a banner at the top of the specs website (or
> each individual spec) that points this out? I'm happy to do the work if we
> agree it's a good thing to do. My suggested wording:
>
> "NOTE: specifications are a point-in-time design reference, not up-to-date
> feature documentation."
>
> // jim
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev