5

So I have seen topics about how to write your first 'Hello World!' and how to start with an IDE. So I was wondering if we can and should use documentation for how to guides.

Example is I was toying with the idea of writing a guide somewhere in the c# tag on how to work with and create custom form controls like buttons that are different shapes, since I see questions about doing this kind of thing pretty frequently.

If this is a valid use of the Documentation site, should "How To's" get their own topic in a tag or just be an example on the topic they are most closely related? Personally I would say a new topic because a guide might include things from multiple topics such as inheritance and threading. But then again I am not even sure if this is a good use of Documentation, so what do I know.

2
  • 1
  • 1
    If you want control over the order, it needs to be an example. If you make it a topic with multiple examples, the examples will sort by voting instead of the logical order you intended. (This is a hint that how-to guides, or basically anything more complex than one or two blocks of code, aren't a good fit for Docs. But because that's not explicitly stated, people are trying it anyway. Maybe if you produce something good, the powers that be will add more tools for organization.) Jul 29, 2016 at 18:29

2 Answers 2

2

Yes, make how to guides! Just make sure you make them Doc's Style.. (and stop calling them how-to-guides :P)

  • Create a topic that is relevantly scoped to the guide and to the tag.
  • Then, create your how to guide as a set of examples that are all narrowly scoped and show parts of how to accomplish the overall goal

This will allow people to come in and find the part they are looking for since it isn't always the case that people will go from A to Z in these so much as they were really interested in how N was done.

Here is a good example:

https://stackoverflow.com/documentation/javascript/4447/indexeddb#t=201607291908027118461

-3

No, Documentation is for filling in gaps in existing Documentation references across the spectrum. Such files and specifications focus on the cut and dry implementation details of a language, so some examples are a good idea, but how-to guides are essentially blog posts and don't belong on Documentation.

1
  • I didn't downvote this, and I do agree that just placing an entire guide or tutorial in one example is a bad idea. That said, I think there is a structure available to document the process of common use cases in Documentation.
    – Travis J
    Jul 29, 2016 at 19:22

Not the answer you're looking for? Browse other questions tagged .