On 23/05/18 10:34, Gareth Roy wrote:
> figuring out how we leverage peoples self-interest could lead to better documentation.
Yes. In my view, taking on and keeping going with a useful document of
interest should be regarded as highly as having a publication in a
respected peer reviewed journal. In science, publication is of such
primary importance mainly because it serves the interests of the authors
- their career progress depends on it. Engineering does not have an
equivalent ethos.
So engineering tends to be hierarchically arranged, and documents are
produced and maintained by means of "management". The KeyDocs is a
scheme that tries to do that systematically. Since we do a good deal of
engineering in GridPP, and we are not as "hierarchically arranged" as a
firm would be, we hit a problem with documentation.
BTW: It's a very similar situation with open source Linux,. Only a
company, e.g. Suse, RedHat, Ubuntu, etc., can arrange themselves
hierarchically to get a high standard of documentation in a "top down
manner". The government and the army can do it as well. But without
something like that, it gets flaky.
I hope that helps explain what's happening ... even though it doesn't
provide a clear path to put things right.
Cheers,
Ste
>
> Thanks,
>
> Gareth
>
> -----Original Message-----
> From: Testbed Support for GridPP member institutes <[log in to unmask]> On Behalf Of Stephen Jones
> Sent: 23 May 2018 09:53
> To: [log in to unmask]
> Subject: Re: gridpp documentation
>
> Hi all,
>
> I'm listening in.
>
> I have a specific action to make it possible to maintain Tom's legacy, and to ensure that some work (that Alessandra's clients have captured) gets rolled in. I'll probably do this is the simplest manner, to be able to address and hence close this pressing action.
>
> But it's right to expand on this. I know Robin wants to talk about this, and obviously Gareth as well (see below). Since we have a HepSysMan in 3 weeks or so, I suggest to use up an hour on this, when some of us are together. It's a general topic of interest to all HEP admins (albeit also a weirdly gigantic topic that keeps climbing out of whatever box you cram it into!)
>
> Cheers,
>
> Ste
>
> PS: Thanks for your kind words about the Example Build. I wrote it and maintained it mainly for myself (similarly with Approved VOs, with
> PeterG.) It seems that self-interest is the best motivation, which gives a clue about things.
>
>
> On 23/05/18 09:08, Gareth Roy wrote:
>> Hi All,
>>
>> I’ve been following this thread with some interest, but I keep feeling
>> that we’re spending a lot of energy addressing the wrong
>> question.Whether we use the GridPP wiki or github.com to some extent
>> doesn’t matter... I think we could make either work, with each having
>> its own strengths and weaknesses (we’ve tried both at Glasgow and I
>> agree with Alessandra that the pull, edit, commit cycle is onerous for
>> updates and small fixes, and I also agree with Robin that wiki’s tend
>> to get stale with orphaned and broken links, and require internet
>> access to get at, so no editing on the plane :P ).
>>
>> I don’t think that’s the real issue though, I think Alessandra hit the
>> nail on the head when she said:
>>
>> “But the problem is not that, the problem is that they are not
>> maintained because people don't edit them and if they don't edit a
>> wiki they have access to they will edit even less a github project.”
>>
>> The fundamental issue is that keeping documentation up to date is work
>> and it’s not seen as a priority. I know there is no additional
>> manpower (in fact less), but unless we somehow change the priority of
>> the documentation in the long list of things we have to accomplish
>> it’s really not going to change. I think keydocs was an attempt to
>> address this but (at least from and external viewpoint) it didn’t
>> succeed as many (all?) keydocs are out of date, and there was more
>> grumbling than actual corrections.
>>
>> Daniela makes a good point:
>>
>> “We really need to par this down to the bare bones, to cut down on
>> maintenance.”
>>
>> I think reducing the effort is important, but I also think we need to
>> examine 1) what is the documentation actually for and 2) what are we
>> trying to achieve... or what exactly is the “bare bones”. For
>> instance, Steve’s:
>>
>> https://www.gridpp.ac.uk/wiki/Example_Build_of_an_ARC/Condor_Cluster
>>
>> Is a masterpiece and I use it a lot but it’s significantly different from:
>>
>> https://github.com/gridpp/user-guides
>>
>> Which I’ve never looked at (as most small-scale users at Glasgow do
>> direct CE submission to us), both have different audiences, goals and
>> requirements but both are “documentation”. Which should be
>> prioritised, which should be focused on? I’m not in a position to
>> really say but if we have finite (i.e. zero) resources something needs
>> to be prioritised.
>>
>> I’m not sure I have an answer, or indeed if there is any solution to
>> this other than paying someone to do it but I do think we have to be
>> clearer in what we are trying to accomplish and where the problem
>> actually is... in general whatever we pick, wiki or github I think
>> we’ll be back again in a year’s time unless we really address the
>> fundamental issues.
>>
>> Thanks,
>>
>> Gareth
>>
--
Steve Jones [log in to unmask]
Grid System Administrator office: 220
High Energy Physics Division tel (int): 43396
Oliver Lodge Laboratory tel (ext): +44 (0)151 794 3396
University of Liverpool http://www.liv.ac.uk/physics/hep/
|
