13

I've been adding some examples to the Ruby on Rails documentation tag and came across a few topics, which have multiple example, which are connected to each other.

E. g.: https://stackoverflow.com/documentation/ruby-on-rails/3606/rails-deployment-capistrano-nginx-passenger-postgresql

Another e. g..: https://stackoverflow.com/documentation/ruby-on-rails/3902/configure-angular-with-rails#t=201607280828428093112

This multi-step examples build together a whole tutorial. A tutorial is not an example in my opinion. I've the following ideas to address this 'problem':

  • Declare that examples have to be independent and provide moderation tools to flag examples, which doesn't follow this rule.
  • If tutorials are wanted in the documentation too, add a new section besides the examples.
3
  • 16
    No, examples should obviously not depend on other examples and certainly not presuppose a reading order. Examples can be deleted/edited/renamed etc. by people who are not aware of the bigger picture. If they want to write a tutorial, in my opinion it should be one (large) example. Commented Jul 28, 2016 at 10:30
  • 2
    Agreed this is unwanted. If people want to create a narrative around a set of related code structures then a blog is probably a better tool for the job.
    – Gimby
    Commented Jul 28, 2016 at 10:58
  • 1
    "A tutorial is not an example in my opinion." Certainly, tutorials should not be shoehorned into the current structure by splitting up over several examples like that. I think a tutorial in a single example (as Gert described) might be okay. I wrote an example that covers a sequence of three steps, and many good examples require that much.
    – Frank
    Commented Jul 28, 2016 at 15:25

1 Answer 1

15

No, examples should be self-contained and should not depend on the order or content of other examples because:

  • The order is not guaranteed
  • The content of the other examples can (and will!) change

Readers of Documentation will find it really frustrating if an example refers to a "previous step" that no longer exists.

3
  • Right, though I guess at this early stage of documentation, this is more of a philosophical question, as in: what do we want it to do? Not: what are the current technical limitations?
    – Cimbali
    Commented Jul 28, 2016 at 15:53
  • @Cimbali unfortunately that isn't actually defined yet. :)
    – Kevin B
    Commented Jul 28, 2016 at 15:54
  • 1
    @Cimbali Fair point. I would also argue that examples should be self-contained. Small, contained examples are easier to parse and maintain compared to larger, sprawling tutorials. Commented Jul 28, 2016 at 15:54

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