Re: Curated subysystems
Luke Kanies <luke <at> puppetlabs.com>
2010-11-01 17:18:17 GMT
On Oct 31, 2010, at 11:29 PM, Daniel Pittman wrote:
> Luke Kanies <luke <at> puppetlabs.com> 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:
>> 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.
> 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.
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.)
>  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." :)
>  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 puppet-dev <at> googlegroups.com.
To unsubscribe from this group, send email to puppet-dev+unsubscribe <at> googlegroups.com.
For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en.