On Oct 31, 2010, at 11:29 PM, Daniel Pittman wrote: > Luke Kanies <[email protected]> writes: > >> As we begin to write actual specs for the work we're doing, we've been >> talking a lot about where the UI ends and the implementation begins and thus >> how much should actually be included in the spec. This conversation led me >> to want to draw out certain subsystems that I think are special because >> they're visible from outside and they should be built with a single coherent >> and cohesive worldview. >> >> For instance, new language features can't just be added, they need to fit >> within the overall language worldview. >> >> After discussing it a bit internally, I have begun to document what I see as >> these curated areas, and I will work to go through and try to describe what >> they do or should look like. One of the goals would be that specs could call >> out changes or interfaces to these curated subsystems directly, so that it >> becomes clear when the user is affected and whether a change is affecting how >> coherent a given subsystem is. > > It would probably be a good idea to provide information on the responsible > person(s) for those areas, also - I know that I would be inclined to contact > the relevant subject matter expert and hash out a plan with them while I was > working on an area like that in a FOSS project.
That's my plan, although it doesn't extend much beyond that. That is, I have a very qualitative plan, not really a detailed idea of what I'll be producing. >> I've begun the list here: >> http://projects.puppetlabs.com/projects/puppet/wiki/CuratedSubsystems >> >> and over the next week or so I'll be filling out each of the actual pages. >> >> Does this seem like the right thing for me to focus on documenting, in terms >> of making it easier to contribute and understand how and why Puppet works? >> Do you have any opinions on how I should build and maintain these documents? >> Should the audience be users, developers, documenters, ...? > > I think the most important people are not-employed-by-PuppetLabs developers, > though probably more on the side of real programmers than "sysadmin with a > Ruby-shaped hammer and a problem to fix yesterday" programmers.[1] > > Folks that the Labs employ directly won't have nearly as much need to read > these, but rather to reference them when explaining to outside folks why their > changes might need extra work or attention before they merge in, I think. This has not been our experience internally, actually. It's been far harder to get across the high-level implementation vision and priorities than one would assume. > I think it would really help if there was a way to turn the abstract ideas > captured in the one example so far into concrete "what does it mean in the > real world" examples. I haven't yet looked at that example, but I'll do my best to keep to specifics. > While looking at the existing language example, incidentally, the second point > seems quite unclear to me: > > Dependencies between sub-states are declared explicitly, not implied by > order or nesting > > ...which is truly a goal of the language, but has me wondering how the > implicit dependency between nested file paths fits into the design goals.[2] Markus wrote all of that and I haven't had a chance to review it yet, so I'll save commenting until I do. > (Also, I wonder where automatic dependency management by system inference > would fit into this, which is something that I consider a potentially > desirable long term goal - but one which is not clearly either forbidden or > permitted by this document.) > > Regards, > Daniel > > Footnotes: > [1] eg: when I am working on something I need fixed, now, in a language > I don't know for a product I don't know I am not going to consult design > style guide documents like these, I am gonna fix my problem, send y'all a > patch and say "I know it sucks, but it works for me(tm), feel free to fix > it for real so the next version doesn't have the same problem and ignore > my code." :) > > [2] I think they are unrelated. I think they /should/ be unrelated. -- The scientists of today think deeply instead of clearly. One must be sane to think clearly, but one can think deeply and be quite insane. -- Nikola Tesla --------------------------------------------------------------------- Luke Kanies -|- http://puppetlabs.com -|- +1(615)594-8199 -- You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en.
