Ha!  That's useful, but I was thinking of *end user* help.

For one example: finding a simple way to document the entire Member's
meeting process, including overview "what this means" and "here's the
steps to actually nominate a new member" bits.   That is, find a way to
have a single URL to read the overview, but also repurpose the
task-oriented steps into the proposed nomination form itself.

So no action needed, just brainstorming - or just saying we're focused
on building code first to see if it'll work.

8-)

- Shane, end-user advocate

Craig Russell wrote on 4/5/17 9:11 PM:
> top posting just because these comments really don't fit well anywhere below.
> 
> Other organizations that I'm vaguely familiar with have relatively large 
> corporate IT staff that manage and maintain corporate records. We choose not 
> to. It's in our culture to make do.
> 
> Even with whimsy tooling, we have canonical representations of foundation 
> data and I don't see these going away any time soon. Perhaps a list of these 
> is what Shane is getting at. All of these files/directories are stored in svn 
> and are accessible via "standard" command line tools svn and vi (emacs if you 
> must ;) keeping in mind that they are utf-8 encoded.
> 
> foundation/officers/:
> iclas.txt
> cclas.txt
> grants.txt
> 
> foundation/members.txt
> 
> documents/iclas
> documents/cclas
> documents/grants
> 
> Then there is the whole LDAP world that can be manipulated with "standard" 
> LDAP commands, which I don't know how to use.
> 
> Is this partly what Shane is asking for?
> 
> Craig
> 
>> On Apr 4, 2017, at 5:08 PM, Sam Ruby <[email protected]> wrote:
>>
>> On Tue, Apr 4, 2017 at 7:30 PM, Shane Curcuru <[email protected]> wrote:
>>> Craig Russell wrote on 4/4/17 7:20 PM:
>>>>
>>>>> On Apr 2, 2017, at 5:42 PM, Shane Curcuru <[email protected]>
>>>>> wrote:
>>>>>
>>>>> Craig Russell wrote on 4/2/17 7:54 PM:
>>> ...snip...
>>>
>>>>> The larger question: is there any standard structure that we can
>>>>> use to create/display/manage documentation for Whimsy bits?
>>>>>
>>>>> We have a lot of different corporate and infra processes that
>>>>> whimsy helps with, but is not necessarily the canonical command
>>>>> line way to do things.  Is there some way we can write once, read
>>>>> everywhere the bits of help docs for our processes?  8-)
>>>>
>>>> I've tried to at least capture what the secretary role does in
>>>> https://svn.apache.org/repos/private/foundation/officers/personnel-duties/secretary.txt
>>>
>>> Excellent!
>>>
>>>> Even though that does not include the mechanical process of doing
>>>> things.
>>>>
>>>> For the board processes, we formerly had agenda.txt which would be
>>>> mechanically edited by each pmc chair, officer, and director.
>>>> Indentation did not matter. But, indentation does matter, but it is
>>>> automatic if using whimsy. If not using whimsy, the entire process
>>>> can be upset by a bad commit. Remember Sally's complaints about not
>>>> being able to grok svn and vi? Do we really need to go back to that
>>>> era?
>>>>
>>>> Stepping back a bit, it's not clear that there is a command line way
>>>> of doing everything that secretary does. Without Whimsy, the job
>>>> would be a mid-level part time paid position, not a volunteer
>>>> position, at least by me. No kidding.
>>>
>>> I think I was unclear: my point is: is there some standard way/place we
>>> can write documentation fro the various little bits of processes that
>>> can be re-used both in high-level docs like /governance/, but also in
>>> specific whimsy processes for the individual steps of a process.
>>>
>>> I'm not suggesting any tool changes with that - just pondering ways to
>>> document all these little steps in a way that could *also* be put
>>> together into documentation that explains the larger process.
>>
>> I'm not certain I understand what you are looking for.  Perhaps a
>> specific example would help.  Since the topic at the moment is new
>> member applications, here are the key portions of the secretarial mail
>> tool for handing such.  First the form that Craig uses for data entry:
>>
>> https://github.com/apache/whimsy/blob/master/www/secmail/views/forms/memapp.js.rb
>>
>> Next (and I sense what is more of interest to you) is the actions that
>> are run to process a member app.  There are block comments for each
>> major step, and if you look into any given step you can see the
>> commands that are issues (svn, ldap, etc):
>>
>> https://github.com/apache/whimsy/blob/master/www/secmail/views/actions/memapp.json.rb
>>
>> Finally, here is the email that is sent out:
>>
>> https://github.com/apache/whimsy/blob/master/www/secmail/templates/mem.erb
>>
>>> I agree - we need Whimsy's automation of individual process steps, and I
>>> welcome the day we store formal corporate records in some
>>> self-validating structured way...  8-)
>>
>> Various whimsy tools originally aimed at doing 90% of the job and over
>> time may have moved closer to 99% of the time; the actual percentage
>> doesn't matter, what is important is that it is not 100%.  In those
>> times, it is helpful to have the base information in a format that can
>> be processed by vim and the command line.
>>
>> Conversely, if we want our data to be more structured, we will need to
>> strive for 100%.
>>
>>> - Shane
>>
>> - Sam Ruby
> 
> Craig L Russell
> [email protected]
> 
> 


-- 

- Shane
  https://www.apache.org/foundation/marks/resources

Reply via email to