Move projects.md to production

[CharliePoole]

I'm hoping for this to be the final review of the projects document. Unfortunately, there seems to be no diff, since I merely moved it. You'll have to look at the commit and make any annotations there.

[ChrisMaddock]

There's still a 'reviewers' comment on the page. Also, did you intend to remove NUnit Results from here, as it's not currently in the nunit github? 🙂

[CharliePoole]

The "Reviewers" note is still there because I wanted to get comments on that point. Should only be the one.

Not sure how NUnit Results got back in as I removed it once!

[CharliePoole]

BTW my assumption on these is that nobody else will merge. I'll wait till everyone has commented and we appear to have agreement, then merge.

@jcansdale You have not reviewed any of these. Are you having second thoughts about the Core Team?

[ChrisMaddock]

Hmm, looks like the docs project isn't there either - did a commit get lost, maybe?

On that note - I'm not sure if I'm a fan of considering the docs a separate project. I'd consider documentation to be more a task of each project, with the central repository just there as a location for it all to be stored.

Maybe that's just me, happy for it to be there if @OsirisTerje and @CharliePoole think it's better separately. @rprouse, @jcansdale?

[OsirisTerje]

My point on the doc repo was that we need to let it get more focus. And since we have it in one place (good or bad, I kind of like it this way, easier to find it all), AND we don't always update - AND it is somewhat hard to navigate for some issues, I feel it can be worked on independently from the code. Having it in one place also makes it easier to document common practices, being it e.g. releases, process, coding standards .... . Having it as a separate project can make it easier to give it focus and attention, the jobs will not drown in other code issues. But we can see how it goes :-)

[ChrisMaddock]

My concern would be that having it as a separate project would lead to it being seen as requiring a distinct team from the development team, when, in my eyes - those adding new features should be updating the documentation in line with this. Having a separate team, if we could find such people, feels like it could lead to a 'not my problem' situation.

I also like the centralised doc repo - for much the same reasons. And I agree it needs more focus, although I'd be concerned separating it out may have the opposite effect to what's intended. Although we can't tell which way it will go until do one or the other - so I agree, we should see how it goes!

[OsirisTerje]

That's a good point. Perhaps we could consider membership in the doc project to be mandatory, if you are a member of any of the other projects then you're also a member of the doc project, but you can also just be a member of the doc project alone. I then assume we will follow the same procedures for updating the docs as any other code. Under roles we now have the line that a contributor can help with documentation, but that again should go through pull-requests. The doc project is special anyway, since it doesn't have releases the same way. My point is really just to get focus to it.

[CharliePoole]

In fact, everyone who is a committer anywhere is also a committer on the docs project. Even contributors (i.e. members of the GitHub contributors team) have write access to the docs.

The docs get updated (if at all) by the same people who write the code. So in that sense, we currently treat docs as a part of the individual projects that are documented.

In the GitHub sense, where project == repo, it's currently separate. But, as is stated elsewhere, the meaning of "project" in the governance documentation is not a one-to-one mapping of GitHub projects.

Earlier, I became convinced by Terje to list docs as a separate project, although the update got lost. Now I"m not sure. 😞

[OsirisTerje]

If we revisit what we mean by a project - frankly we haven't clearly specified what a project is, it is a term we just use. But, a project is something we need to maintain.
The doc repo has its own list of issues, where we add documentation issues. In addition there are issues in the code projects with the label isDocs, and just looking at the nunit project, we have 68 such issues there. This means we have documentation issues both in the code projects and in the documentation project. If we keep the documentation as a non-project, then should we have issues there? Because if we have, who maintain that? My point in suggesting it as a project was to get attention to these too. Without attention to them, it is a bit happy-go-lucky if anything is being done with them., For the nunit project we have 67 closed doc issues, and one open, for the docs project we have 67 open and 121 closed, and a lot of the open ones are rather old. (The nunit may be closed because they have been moved ofc, @CharliePoole would know that).
The issues in doc are not grouped by code project either, but are a long list of issues. So to me it looks like we need to maintain the docs, and it seems it needs to be maintained separately.

[CharliePoole]

It's true that projects.md doesn't define exactly what a Software Project is, except to say "Here's the list." In practical terms that may be sufficient.

However, my point was that there is a distinction between how we want to organize our projects and how we document the way they are organized. For this discussion, I think we want to decide whether docs is a separate project, not whether it should be separate. My reasoning for that is that we will never finish this review if we keep changing the very things we are trying to document. So, if we are willing and able to change something in the next few days, this document can reflect the change. OTOH if it's going to take several weeks, I believe we should document the current situation and update later.

So... is docs now a separate project.

In favor...

• It has a separate repo
• It's web based and published on its own schedule

Against...

• It does not have a separate team or team leader

I am mostly on the "Against" side here because I think that for the purpose of governance, a separate team is what makes something a project. Of course, we share resources across teams, but for a project like the framework or the engine our goal is to have people dedicated to it. For docs, we actually don't (at least I don't) want to have a separate team. We want the people working on the code to maintain the relevant docs.

I agree that we need to do something to give the docs more priority, but I don't think finding separate people to write them is the answer.

[ChrisMaddock]

I agree it doesn't currently function as a separate project, and I would be wary of making it one, until such a point as we find a team interested in maintaining it.

[rprouse]

I do not see any changes to the document, just the move to production. Am I missing something? Based on that, my comments haven't changed much.

As for docs, I don't think it should be a separate project and I would never want to see it maintained by a separate team. I think it is the responsibility of each project to keep their section of the docs up to date and organized. We can mention that in the document, but do we need to be excessively explicit?

[CharliePoole]

@rprouse We have not reviewed this previously. It looks a lot like the two others because it incorporates roles and duplicates part of projects.

[rprouse]

This is the same projects.md that we reviewed in #1. I was confused because I thought this PR should include the changes based on that discussion, not just the move. Looking at it again, I see that you have made the changes as suggested in #1. The changes look fine.