How, precisely, can we improve?

Christopher Allen cma at bitemyapp.com
Thu Sep 29 05:10:30 UTC 2016


I was thinking of what Richard was describing as shoring up the
insufficiencies of the existing infra, rather than something to be
directly targeted in any possible alternative.

Hypothetically could be made automatic or a git hook, if you wanted
things like last-modified timestamps injected into the documents. I
don't have strong feelings on this other than to say that there are
simpler ways to represent and serve documentation that let people use
whatever layer on top they want.

For example, if someone _did_ want the readthedocs specifically, they
could mirror the repo into the RTD branch and point it at the docs
directory or similar.

Git repos mean not being blocked by trac slowness/downtime, the
content being more widely mirrored, all kinds of nice to be
potentially had.

On Thu, Sep 29, 2016 at 12:01 AM, Moritz Angermann
<moritz at lichtzwerge.de> wrote:
> That is an interesting way to interact with the wiki, I had
> never thought about using it that way!
>
> So what you are proposing is a version controlled text based
> documentation system, precisely you can download the wiki and
> use your own cli/editor finding/indexing tools on it?
>
> This would of course be covered by almost any of the static
> side generation tools that work off of git I assume.
>
> I’m still uncertain how to accommodate Richards dynamic features
> into this? And I believe he’s not the only one who relies on them?
>
> Regarding the stale wiki page issue, scanning the history for
> files could potentially provide a list of “old” items, and
> eventually one could just delete them from master (automatically?)
>
>
>> On Sep 29, 2016, at 12:37 PM, Christopher Allen <cma at bitemyapp.com> wrote:
>>
>> Makes sense, no problem!
>>
>> I think my main personal complaints with docs have been:
>>
>> Poor discoverability — neither wikis nor search solve this, I want a
>> dir listing.
>>
>> Slow search — almost every wiki has slow search. bouncing out to
>> google is annoying. just let me grep.
>>
>> Broken links — this is particularly annoying as unis like to shut down
>> student accounts hosting papers. I had to do some archaeology on an
>> obscure Chinese FTP server to find some of Don Stewart's papers and
>> slides recently.
>>
>> I believe there can be a convincing solution to all of this and more.
>>
>> On Wed, Sep 28, 2016 at 11:33 PM, Moritz Angermann
>> <moritz at lichtzwerge.de> wrote:
>>> Chris,
>>>
>>> I’m all in favor of a better system! My only intention was to point
>>> to a solution that might help with the current system, right now.
>>>
>>> I’ve come to use that feature quite frequently even outside of this
>>> specific use case, as many of the results are often full of
>>> interesting yet stale information.
>>>
>>> Anyhow, I don’t want to obligate anyone to do anything, and if this
>>> was perceived that way, I’m truly sorry.
>>>
>>> Cheers,
>>> Moritz
>>>
>>>> On Sep 29, 2016, at 12:24 PM, Christopher Allen <cma at bitemyapp.com> wrote:
>>>>
>>>> Why not just do the better thing to begin with rather than obligating
>>>> people to think to use this feature? Most, even those who know it's an
>>>> option, aren't going to think to do this in the heat of trying to
>>>> track down an answer to something.
>>>>
>>>> On Wed, Sep 28, 2016 at 11:08 PM, Moritz Angermann
>>>> <moritz at lichtzwerge.de> wrote:
>>>>> Just a quick note: Google provides the “Date range” filter found under
>>>>> search options. This allows to narrow down the date range.
>>>>>
>>>>>> On Sep 29, 2016, at 11:55 AM, Bardur Arantsson <spam at scientician.net> wrote:
>>>>>>
>>>>>> On 2016-09-29 04:43, Richard Eisenberg wrote:
>>>>>>> Here's a pre-proposal (which could be formalized into a proper proposal)
>>>>>>> to address the wiki discussion:
>>>>>>>
>>>>>>> - Configure the wiki to display the date of last edit prominently.
>>>>>>>
>>>>>>> - If the date of last edit is sufficiently long ago (1 year?) loudly
>>>>>>> warn the reader that the content may be out-of-date.
>>>>>>>
>>>>>>
>>>>>> I see at least one major issue with this: Search engines don't care if
>>>>>> you write "THIS MAY BE OUT OF DATE" on the page. It's a perennial
>>>>>> problem that search engines keep linking out of date material just
>>>>>> because such material tends to be linked more (simply because of age).
>>>>>>
>>>>>> There are few tings as infuriating as going through a bunch of search
>>>>>> results and getting pages from 10 years ago.
>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> _______________________________________________
>>>>>> ghc-devs mailing list
>>>>>> ghc-devs at haskell.org
>>>>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>>>>
>>>>> _______________________________________________
>>>>> ghc-devs mailing list
>>>>> ghc-devs at haskell.org
>>>>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>>>
>>>>
>>>>
>>>> --
>>>> Chris Allen
>>>> Currently working on http://haskellbook.com
>>>
>>
>>
>>
>> --
>> Chris Allen
>> Currently working on http://haskellbook.com
>



-- 
Chris Allen
Currently working on http://haskellbook.com


More information about the ghc-devs mailing list