I created the .NET "Networking" topic and it has been sitting pending review for a full day already. Just wanted to make sure that it is because everybody is very busy, and not because it is only visible to me for some reason. :-)
@AdamLear Uoooh, super-secret SO internal code!! :-)
It’s finally here!
Post-Start-Of-Beta Announcements
November 19th New Features Announcement
The Purpose Of The Beta
During this, the private beta, we’re looking to squash a bunch of bugs and prove out the model and tools we’ve built.
If you see a bug, have an idea for a new feature or an...
How do we handle duplicate documentation? Right now it looks like there's a good C# topic "C# 6 Features". But there is another duplicate "C# 6 Feature" topic.
There are also duplicates "String Interpolation Topics"
sort of hard to make one while everything keeps changing
@JoshVarty delete one, move the relevant stuff over to the survivor - you can do it as a single "change" too, submit two drafts at once (I'll slap a screenshot together real quick)
ha, I say that but I think my last deploy broke the delete button!
Should I be aiming to document classes, methods or domains? e.g. The Parallel class have several methods. Should each method get separate treatment, the class as a whole or should there just be a topic on parallel processing?
it's really what is most useful, which varies by what you're documenting - I would suggest coarser than method level; Parallel Processing Topic that also links to an overview the Parallel class (a separate Topic) would be my inclination
I was about to ask this: docs-beta.stackexchange.com/q/52/134 has there been further discussion about this in chat? if I want to add .NET documentation (I'm thinking regex), do we want examples primarily in C#? do we not care about the chosen language? do we want to cover several important languages, like MSDN usually does?
hm, I think I need to give this more thought before I start documenting away at .NET's regex stuff. the majority of the regex documentation on MSDN is really solid, but there are a few edge cases that aren't covered or explained ambiguously.
is there side-by-side view for proposed changes yet? I tend to have a really hard time piecing together the old and new version when looking at the inline comparison heavily edited posts.
The documentation site does not have an hierarchy. This is by design. I do think it is important to think about the range of topics before writing one.
I noticed people just requesting topics and start documenting. Let's say I am to start an XmlSerialization topic. People keep on adding example...
What is the proposed way to deal with "sub-topics"? E.g. we already have one topic for C# keywords and one for LINQ that gives the examples for all the operators/keywords in one big list which quickly becomes unmanageable. Ideally there should be a Topic per LINQ operation (e.g. Where, Select etc.) or C#keyword, and one god-topic that combines all the sub-topics.
make the god topic, put some of the basic examples in to it, and link out to the more details topics from remarks
there's not a strict hierarchy 'cause that gets real contentious real quick; though we intend to surface "related" topics based on links (and maybe keywords)
@Kevin the only issue is that because topics must lead with examples, which then forces the god topic to have examples for all the "operators", e.g. the LINQ topic currently has 44 examples!
Where do you then put the examples? In the summary topic or the child topic, or in both?
I understand that structure can get contentious, but on the other hand, documentation is inherently structural in nature
@Riko there's no need for a LINQ overarching topic to have examples of all operators, provide the others are linked - it stretches credibility that someone needs to know about every operator on one page, someone just searching LINQ probably wants what... Select, Where, Single, and ToList(). GroupBy, OrderBy, ThenBy, GroupJoin, Intersect, etc.? nah
Mm, yeah, that sort of thing gives me some doubts about how we're structuring the Syntax/Parameters sections. Gonna definitely be keeping an eye out for auto-flaggable things, but also will need ways to resolve those flags without too much pain. In this case, I think Syntax just needs an edit to pare it down
It’s finally here!
Post-Start-Of-Beta Announcements
November 19th New Features Announcement
The Purpose Of The Beta
During this, the private beta, we’re looking to squash a bunch of bugs and prove out the model and tools we’ve built.
If you see a bug, have an idea for a new feature or an...
The documentation site does not have an hierarchy. This is by design. I do think it is important to think about the range of topics before writing one.
I noticed people just requesting topics and start documenting. Let's say I am to start an XmlSerialization topic. People keep on adding example...
