[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: Cleaning up the FAQ

From: Johan Corveleyn <jcorvel_at_gmail.com>
Date: Thu, 23 Jun 2016 00:33:19 +0200

On Wed, Jun 22, 2016 at 2:07 PM, Stefan Hett <stefan_at_egosoft.com> wrote:
> On 6/22/2016 1:38 AM, Mark Phippard wrote:
>>
>> Sounds good in general, but would it be better to just create a new page
>> and leave existing one in tact so that links to entries all remain
>> functional?
>>
>> Also, it might be a better question for users@ list. I cannot think of any
>> reason for a dev to object to someone who wants to put in the effort. Users
>> might have more feedback on what is still valuable.
>
> I'd second this suggestion. This would allow keeping the links intact.
> Obviously the menu/navbar entry should change to state something like: FAQ
> (old) or FAQ (deprecated) with the new FAQ page then replacing the old one
> (with the filename being something like faq_new.html or faq_v2.html for
> instance). Eventually that link could be dropped at one time with the
> faq.html page still being available for some extended period at the
> appropriate time.

Hm, I think I'll go for stsp's suggestion, to move deprecated
questions to the bottom, but keep everything on one page.

Something like this:
-----
For questions related to deprecated SVN versions, click here (-> #deprecated).

TOC (recent)
FAQ (recent)

=== separator / heading / whatever ===
#deprecated
TOC (deprecated)
FAQ (deprecated)
-----

(that first sentence needs some tweaking)

I'll also follow through on Mark's suggestion to ask for feedback on
users@, but first want to get the above structure in place to give
users a more concrete idea.

Note: my web designer skills are totally mediocre. The best I can do
is work within the existing design and move things around a bit --
people with more skills in this area are more than welcome to help
:-).

>>
>>
>>> On Jun 21, 2016, at 7:20 PM, Johan Corveleyn <jcorvel_at_gmail.com> wrote:
>>>
>>> I think our FAQ is a bit of a mess (with all due respect to the people
>>> who have contributed to it over the years -- time has just taken its
>>> toll). Some questions are no longer relevant for recent releases (e.g.
>>> documented workarounds for problems that have since been fixed; or
>>> referring to BDB or subversion 1.0 or ...).
>>>
>>> I'd like to clean it up a bit:
>>> 1) Move anything only relevant to old releases (anything < 1.9 or <
>>> 1.8 (?)) to a separate page (faq_old.html or something -- linked from
>>> the main faq with a link somewhere at the top "Questions about older
>>> releases").
>
> To be consistent with the statement of supported versions, I'd at least keep
> everything relevant to the old-stable version (aka: 1.8) in the actual FAQ.
> Maybe moved to a section for old-stable, to point out it no longer applies
> to the current stable version. But dropping documentation for a still
> supported (even if only partially supported) version seems to be premature
> IMO.

Ack. Let's keep everything that's still relevant for 1.8 and later in
the "main FAQ".

>>>
>>>
>>> 2) Remove some questions that are unlikely to be relevant /
>>> interesting anymore (e.g. "How is Subversion affected by the 2007
>>> changes in Daylight Savings Time (DST)?")
>
> For outdated information: Fully agree.
> For BDB-related information, I would not yet call it outdated though. At
> least not before BDB support is dropped from SVN completely (and then
> (re-)move that information at the same time when the old-stable version no
> longer supports it), since it's still applicable to the current supported
> version.

Hm, I'd say we move BDB-questions to the deprecated section in the
FAQ, since it's been deprecated since 1.8 [1], which is our old stable
version. I'm not talking about removing information, but let's move
them to the deprecated section.

[1] http://subversion.apache.org/docs/release-notes/1.8.html#bdb-deprecated

-- 
Johan
Received on 2016-06-23 00:33:44 CEST

This is an archived mail posted to the Subversion Dev mailing list.