search

CaptainCodeman / rdx-demo

Demo app for rdx
ISC License
7 stars 3 forks source link

Possible Documentation? #1

Open petecarapetyan opened 4 years ago

petecarapetyan commented 4 years ago

DJ and I both indicated a desire to contribute documentation, if such would be helpful.

In my case, I'm adopting the rdx for our little team - which is characterized by non-compliant developers who appear to neither understand nor indicate an interest in the finer arts of decoupling and separation of concerns.

Because of this, I'll have to document the heck out of lots of stuff that would be obvious to someone like Simon. So, it might not be appropriate for this project.

I thought maybe I'd indicate an interest here, but produce the docs on my own project, then if any of it seemed appropriate DND it to this as well, and/or filter/edit as desired? Or, if alternate proposals ....

djlauk commented 4 years ago

I just worked through rdx-demo while trying to make it the starting point for a side project. I would volunteer to write a "narrated walkthrough" (in lieu of a better word) of the code. Which parts are where and which purpose do they serve, that sort of thing.

Would that help?

Writing documentation is part of my process of learning things.

djlauk commented 4 years ago

@petecarapetyan hinted me at this wonderful talk about documentation https://www.youtube.com/watch?v=t4vKPhjcMZg

Quick summary of the talk are these 4 categories:

  1. Tutorials (step by step, learning oriented)
  2. How-To guides (step by step, problem oriented)
  3. Topic guides / discussions (understanding oriented)
  4. Reference (information oriented)

@CaptainCodeman, which of these types of documentation would you deem most beneficial to this project? Is there anything you'd like me to give a shot?

I'd guess (1) or (2) would make sense, but if it shall serve as an example for the (lit-element) community, I could imagine (3) might make some sense as well.

CaptainCodeman commented 4 years ago

Yeah, I think github issues are inevitable for 3, so 1 or 2 is probably most useful for most people.

I did start on an initial "why" blog post that should cover the reason for it, history and thinking behind it. That's really the "why might I want to try this?" and then you'd get into providing a more step-by-step tutorial which I think makes sense for 1 most.

Some example apps showing particular patterns and approaches would help for 2 maybe ?