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
