Looser merge requirements for doc files?

[MattWhilden]

See dotnet/coreclr#894. This poor doc has been stuck for a while in with minor edits happening the the PR while the bulk of the goodness is just being "delayed".

I really would prefer these things kinds of things to feel more like wikis than battle hardened source.

There was some pushback to using the Github wiki because we wanted to have all of the docs version with the code. I think explicitly loosening the merge requirements for MD files maybe help us end up in the best of both worlds. Something like "all sane looking changes will just be merged, cleanup can be addressed in later PRs" is probably sufficient.

/cc @josteink @richlander @jkotas

[josteink]

In that specific case, I've already made my position known.

As for general rules regarding documentation, I agree having less "regime" and more wiki-like process will probably lower the bar to getting documentation submitted. Being too strict always runs the risk of people not bothering to document things at all.

Finding the precise line where you say "this is good enough, that isn't" is a tough one though.

IMO it's easier to find things which shouldn't count as grounds for rejection, than finding clear points for granting approval.

I think some good general principles would be to not turn down a PR unless:

• it contains factual errors.
• it contains confusing or jarring internal inconsistencies for things like names used, folders used throughout a procedure, or in other ways makes it likely that the documentation will be misunderstood.
• it doesn't represent a general improvement of the total documentation.

I vote that inconsistent formatting/naming relative to other documents somewhere else in the repo as a whole should not be grounds for rejecting a PR.

Having one repo-wide standard would be nice, but if every contributor trying to improve documentation here and there needs to scan every MD-file everywhere and look for de-facto conventions, it's going to be hard to be a contributor and over time even harder to find contributors.

Too vague? Too lenient? Any other opinions?

[jkotas]

dotnet/coreclr#894 was stuck because of @ajensenwaud has been presumably busy with other things and did not have a chance to take care of the PR. It is the rare case. The typical situation is that person submitting PR deals with minor feedback quickly. We had many doc updates with minor feedback that went through quickly without a hitch.

If we start assuming that a minor feedback is not going to be addressed quickly, it is ultimately more overhead and noise, to optimize for the rare case.

I do not think we are trying to have any repo-wide standard for the documentation, but having a single doc to somewhat consistent would be nice. My minor feedback for dotnet/coreclr#894 was based on glancing at the rendered view - one line formatted one way, and next line formatted different way, etc.

[tony]

re: https://github.com/dotnet/coreclr/pull/894.

I hope I didn't give the wrong impression. I was QA'ing the LLDB script on a new box. All those notes were mine added just recently for a few minutes. The whole PR was more than just docs, it added a script.

Regarding comments, it depends on the system they have, some certain software projects I like (without giving names :smile:) are stuck systems where doc changes are way too bureaucratic. Notably because they keep docs on the same tracker and systems that the code goes on. Even if standards are made, it's still like playing football to get simple stuff committed.

Low-hanging fruit are normally easy to move through, but if that comes up often, that's kind of why GH has wikis - it's separate from the code and it's all live.

I do agree there should be some workflow / standards regarding docs, probably just basic things.

Question: Are there any decisions already made regarding docs we can note / link to so we don't overlook things we've already agreed upon? Are we already in consensus that docs should stay in this repository (and therefore the same issue tracker)? That markdown is the standard?

[richlander]

I moved the docs to the code repo since the GH wiki is (sorry) not that great. Number 1 on my list is that there is no PR mechanism for wiki docs. So, instead of PRs for nothing, we now have PRs for everything. I also really disliked how links worked. Separately, I see a lot of value having the docs version with the code.

I agree with @jkotas that most doc PRs have been merged very quickly. Also, if I look at this PR, the reviewers have been very quick and diligent. That's very positive.

[kangaroo]

I'm pretty strongly against differing contribution bars for docs versus code. Docs are equally as important and need scrutiny, and it sets a bad precedent. Consistency is better imho.

[tony]

Regarding the issue:

I agree @jkotas. The issue cited an exception to behavior I've seen. My first two doc contributions got merged in less than two hours, after @ajensenwaud's was deemed good to go (but before merge conflicts were squashed).

The issue with those docs being merged in invited a pile-up with FreeBSD contributors, one way or another.

Docs in repo:

The major plus with keeping docs in the code is consistency with wherever the code is at.

Once we get moving, it's also nice to checkout a tag and see those docs at that point and time.

Standards

IMO, as the project grows we can swing back to it. I think a simple guideline as @jkotas mentioned will probably do the trick for the time being.

I do imagine docs growing at a rapid pace however. Before long we may want to adopt something that allows API docs, PDF generation and interlinking. Is there any solutions Microsoft or the Mono project likes for this?

[richlander]

I agree with @tony that checkout a tag and getting the associated docs will be a wonderful thing.

The ASP.NET team has adopted ReadTheDocs for ASP.NET 5, hosted @ http://docs.asp.net. It has PDF generation and interlinking. We're looking at using the same solution for official .NET Core docs. Would love input on this. @blackdwarf (new to the .NET Core team) is looking into this.

Separately, I'm hoping we can close this issue now. I think that we've decided that we don't have a significant problem and that we're going to continue on as-is. Not making a critique, but we're still waiting on the commits to be squashed for the referenced issue, so the blocking issue isn't about doc standards or a slow review cycle.

[tony]

That's good to know, I've been very happy with RTD, Sphinx and reStructuredText / docutils. cmake and llvm are using it as well.

Let's keep chugging away. Good night

[richlander]

If you can share links to their doc sets that use the same tech, that'd be cool.

My thinking is:

• Use RST for RTD
• Use MD for the repo docs

Good?

[tony]

We can open a separate issue to discuss how sphinx can be laid out, if you wish.

If you can share links to their doc sets that use the same tech, that'd be cool.

Can you clarify what you mean by that?

My thinking is:

Use RST for RTD Use MD for the repo docs

Typically most projects just use sphinx (which builds to RTD via git hook, and can also be built / tested / previewed locally).

• https://github.com/llvm-mirror/llvm/tree/master/docs
• https://github.com/django/django/tree/master/docs

GitHub supports .rst through rest2html. It pipes straight through docutils. It's not sphinx (no interlinking or language-specific domains.

I think to continue that discussion is, if the docs were split between a RTD set and repo docs, which content should go where.

Also, how far is the dot net / ASP team along with sphinx? Have they written a C# domain yet? That'd be a fun thing to write

[richlander]

You answered my question.

Never mind my segmentation. What I'm really meaning is that I see a world where we use RST for the official .NET Core docs, and still enable/encourage using MD for docs that are more germane to CoreCLR/CoreFX repo users.

The .NET Core Docs will conceptually span repos, so it is unclear where the docs should go.

Yes, the ASP.NET folks have started on the C#/MSIL domain.

How about we continue this conversation on a different issue - dotnet/coreclr#948, so that this conversation can close down.

[MattWhilden]

Seems like the consensus is to maintain things as they are. That is completely acceptable to me. Thanks all for the feedback.