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. > 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. 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. 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] (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. -- ✣ Daniel Pittman ✉ [email protected] ☎ +61 401 155 707 ♽ made with 100 percent post-consumer electrons -- 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.
