Re: [boost] Moving wiki/Guidelines/WarningsGuidelines

Subject: Re: [boost] Moving wiki/Guidelines/WarningsGuidelines
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2018-08-02 08:55:17

On 2 August 2018 at 10:42, Stefan Seefeld via Boost
<boost_at_[hidden]> wrote:
> On 2018-08-02 04:18 AM, Mateusz Loskot via Boost wrote:
>> On 2 August 2018 at 10:09, Stefan Seefeld via Boost <boost_at_[hidden]> wrote:
>>> On 2018-08-02 03:59 AM, Mateusz Loskot via Boost wrote:
>>>>
>>>> Paul Bristow suggested [1]
>>>>
>>>> "We might also re-host this document somewhere on github/boostorg?"
>>>>
>>>> [1] https://lists.boost.org/Archives/boost/2018/07/242617.php
>>>>
>>>> I'd like to edit and move the wiki page away from Trac.
>>>>
>>>> IMHO, it is reasonable to host it not on GitHub wiki but
>>>> on boost.org along other guidelines, for example, at
>>>> https://www.boost.org/development/warnings.html
>>>>
>>>> - It is easy to update website via pull requests.
>>>> - Any updates would be a subject of some review at least
>>>>
>>>> Thoughts? Objections?
>>>
>>> I don't think this is a good idea, as it contributes to the proliferation
>>> of
>>> locations to look for to find information (or to contribute updates),
>>> which
>>> will also result in duplicate (in the best case) or contradictory (in the
>>> worst case) information.
>>
>> You've lost me.
>> I'm suggesting *single* place to maintain all the common Boost development
>> guidelines, namely boost.org.
>>
>>> Ideally, boost.org should consist of a *very* small
>>> number of static pages (a hub, really) with links to other pages, such as
>>> project-specific websites (e.g. http://boostorg.github.io/
>),

>>
>> Clearly, we have a hierarchy of the recommendations here:
>> - common guidelines
>> - library-specific guidelines based on/extending the common ones
>>
>> I'm talking about common guidelines here, not the library-specific ones.
>>
>>> or the wiki (https://github.com/boostorg/boost/wiki).> Unsubscribe &
>>> other changes:
>>
>> I suggest to not to maintain common guidelines on GitHub wiki or
>> anywhere else - Wiki is volatile,
>> too easy to edit by too many or too easy to sneak unwanted edits.
>
>
> I think it's a judgment call, really:

Yes, it is.

> I see your point, and I agree: on the one hand we have version-controlled
> (relatively static) content, on the other we have easy-to-change volatile
> content.
>
> If it were for truly static content, I would wholeheartedly agree with you.
> But a document describing how to deal with (compiler-specific) warnings is
> inherently a moving target, and thus will quickly get stale unless it's been
> actively maintained (read: updated regularly). And if it's hard to change,
> people will just add their own guidelines elsewhere...

My judgement was that editing documentation via a GitHub pull request
is easy and convenient.

Since, I'm not even close to a position to tell where to host stuff,
I'll wait for the PSC or other authoritative voice to tell where it should go.

I just offered help to migrate the wiki page content to .html file in
boostorg/website.
Actually, it would be better for my own health if I could migrate it
to Markdown ;)

In fact, I would like to see https://github.com/boostorg/docs where all static
documentation is maintained in form of plain Markdown files.
That, however, is a topic for another hardly-ever-ending thread...

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net