We use design documents at work to ensure a clear understanding between the requestors, product owners, and developers. There’s a request document that outlines what they’re looking to accomplish, we produce a design document that outlines what we’re doing and how that will be accomplished. External dependencies use the design document to implement their required services — if I have a design document that says I’ll pass x (required), y (required), and z (optional) to a WSDL and end up with an object in the application database where a=x, b=y, and, optionally, c=z … they’ll whip up an endpoint that takes the parameters, performs the required actions, and builds the object I need. Once everyone is in agreement that it’s what they want, it’s reasonable (security, ROI), and possible … developers get to work. Tests are built against the documented functionality, and we know we’re done when the tests pass. If the users want something changed, the design document is amended, a quick feasibility/reason-ability review is performed, and development work commences.

I thought of this process after observing some people push PRs for major overhaults into a few open source projects only to have the PRs rejected as, essentially, not the direction “we” want to go. On the other extreme … I’ve made some changes to open source apps — in some cases, those were bug fixes, and I’ve pushed the changes back to the main project. But, when I’ve changed functionality. I’ve made those changes to address a specific need I have, and I leave the changes in my own fork. Which has the detriment of, potentially, not providing useful functionality to the main project. While it’s perfectly reasonable to put a lot of time into a major change that you need anyway (and, potentially, offer those changes back to the community) … it is terrible to put a lot of your time into something for someone else and have it rejected. And while not engaging with the project maintainers to see if they’re interested in my derivative work saves effort for me, it reduces innovation (how many people actually run through all of the forks of a project to see if anything ‘interesting’ happened elsewhere?).

Obviously, the answer isn’t for projects to accept effort just because it’s a significant investment on the contributor’s part — there should be some mechanism for ensuring what you’re about to delve into is something the project maintainers actually want. Which is what made me think of the design documents we use at work.

If a project had a design document that detailed what it waned to do, how it was doing it, and potentially a section for desired future features and functionality … it would provide a guideline to anyone looking to contribute. A change that doesn’t impact functionality (e.g. a bugfix) can be worked on and submitted for inclusion in the project as occurs normally. If you want to change something about how the application works, you first submit a PR against the design document. Outline what you want to do, how you want to do it … maybe even a quick mock-up (I use Pencil Project for mock-ups where I’m uncertain the final project will be approved, HTML web code when I know the project is a go and want a head-start on my development … but I also accept the risk that I ‘wasted’ a few hours building the design document wireframe if the project gets dropped). Want to work on one of the ‘desired future’ items? Modify the design document to include that functionality and how it’ll be implemented. Discussion about the approach refines what you’ll actually be doing, and you’ll understand if the project maintainers are interested in your contribution before dedicating hundreds of hours to development.

Some projects are interested in “bugfixes only” — which can be stated in the contributing guidelines. In this example, I developed a quick script to produce in-scope user lists. I don’t want to include other details about the identified users, I don’t want to find the first n levels of reports, etc. It’s exactly what I needed, and I’m putting it on GitHub as an example — using Python to search an LDAP directory and using recursion with back-linked attributes.

Projects that are open for collaborative contributions, though, can include the design document location in their contributing guidelines. Initial contributions are made against the design document, discussed, and approved or rejected. Once approved, code can be developed to the new design.

Scott and I were discussing methodologies in open source development. In some ways, I find open source development to be “developer’s id”. Unlike a development job, where you need to do all of the tangentially related (or completely unrelated) tasks mandated by your company, you volunteer your time toward whatever you want to work on. If developers don’t find value in project management, then project management won’t be done in the open source project because no one devotes time to project management. If developers don’t find value in testing, testing won’t be done in the open source project because no one dedicates time to testing. Ideally, people who are interested in all aspects of development would get involved in a project, but what I’ve seen in the open source community is developers.

The problem this creates is that a larger project doesn’t really have any direction. The functionality is almost an emergent property of individual development efforts. I had a friend who worked at MicroProse back in the early 90’s. I remember him talking about a debate between military consultants and UX designers about the direction of control in a military aircraft game (IIRC as they built the first mouse-controlled game). They made a decision, and there was a reason for the decision (memory is the “true to real controls” side won and the “logical” side lost). In a company with low turnover, it was easy enough to retain that knowledge. Some new UX tester says “hey, this is counter-intuitive and makes gameplay more difficult”, they get “the spiel” about verisimilitude.

Most companies have evolved from relying on this sort of tribal knowledge. Memory is faulty (I don’t remember why we decided to do xyz ten years ago … you?), low turnover isn’t as common (my most recent hiring adventure clued me into the fact that a long series of 6-18 month contracts is fairly common in IT ops), there’s a significant level of effort involved in maintaining what amounts to an oral tradition (when I worked somewhere with the ‘oral tradition’ approach to IT architecture, I wrote up my day-long spiel so I could hand it to the next new guy and avoid straining my vocal cords), and “we all just know” certainly doesn’t fly if the company is attempting some sort of regulatory or ISO process validation. Software development companies have adopted application lifecycle methodologies, manufacturing companies have adopted production methodologies, etc that include documentation. What we intend to do, why we’re doing it, and how we’re doing it.

In theory, a new software developer coming into a firm that uses ITIL could use their first week to read through the service catalog and gain a fairly decent understanding of their job. As with most theoretical designs, I’ve not encountered a real implementation that was 100% adherent to a standard practice. That may mean that the practice was adapted to fit the individual organization/product/project, or it may mean that the company took the “start somewhere” approach and has implemented the methodology for new projects. But the result, by any road, is that there’s some tribal knowledge.

What does this have to do with open source development methodologies? I’ve started to think of open source projects as companies with really high turnover. Back in the 90’s, 104% annual turnover was a cause for celebration at the call center I supported. As in statistically every single person who worked for the company on 01 January had quit, and by 31 Dec some of their replacements had quit too. Of course, there were long-term employees and a lot of people who only stayed on for a few weeks who averaged out to 104% turnover. But watching development in a few larger open source projects brought the call center to mind. There are a handful of contributors who are consistently involved across multiple years. But there are a lot of people who pop in to create a PR for a single issue or feature that particularly touched them. This creates a scenario where maintaining an oral tradition and allowing PRs to guide the project roadmap is ineffective.

Scott and I were discussing a methodology for use in open source development, and I mentioned that there are some projects that someone posted online as an open source contribution where they’re not looking for input. I have some of these — if someone finds a bug in the code I wrote to gather MS Teams usage stats, I appreciate their help. If they want to change the report format, or what’s being reported, or … well, it’s a script I wrote and use for a specific purpose, and that’s what it does. Feel free to make a fork and adjust the report to suit your needs. But I’m not going to merge a PR in that keeps five years worth of data because I don’t want five years worth of data. And that’s a perfectly valid decision for code I built that I shared in case it helps someone else who needs to achieve a similar goal. I call this a dictatorial project — there’s an individual that makes the decisions. If you want to change something about how the program works, you should run it by the dictator prior to putting a lot of effort into it. Or plan on making changes in your own fork.

There are oligarchic projects — those may be corporate sponsored projects or projects owned by a group of private individuals. As with dictatorial projects, there are a small number of people “in charge” who decide if PRs are merged or not.

And there are democratic projects — at least in theory. I don’t know if this ends up being true in practice anywhere. But, in theory, a large community of developers or users would drive the direction of the project.

I suppose, if I’m discussing theoretical repository management types … I could add in mass chaos. Open for anyone to merge changes. This is an approach that’s worked surprisingly well for Wikipedia, so I suppose it could work for a smaller code base. Someone merges in some malicious or flawed code, someone else puts in a fix.