Port wiki FAQ into How Do I section

[cldwalker]

Once #4 lands, we should clean up and import questions from https://github.com/LightTable/LightTable/wiki/FAQ

[cldwalker]

Some thought should be given to question organization before copying questions over. Should also discuss if FAQ is still valuable for some questions

[Robsteranium]

I think this is a really important issue. I think the question-answer structure is fine if you have a specific question but that it can be a bit unwieldy if not. In particular, it's kind of impossible to get a good overview from an FAQ - the kind of overview that's vital for phrasing specific questions! I think it's fine to extend the FAQ as per the intent of this issue but I wonder if some more structured documentation might be a useful addition...

I just read http://jacobian.org/writing/what-to-write/ which suggests three main areas of documentation:

• Tutorials - quick, easy, first impression (give people a feel for the project within a lunch break)
• Topical guides - narrow focus to cover certain topics in depth (need not be collectively exhaustive)
• Reference - thorough API documentation for those who already know part of the API (and need e.g. details on the parameter of a function)

There are a few tutorials, which is great. They're a bit disparate at the moment, perhaps there should be a single list with a brief summary of what you can learn from each?

I wonder if a few of the FAQs could be canabalised to create topic guides? We could group issues to do this and draw in some of the tidbits hidden on the mailing list archives. I think the Ruby on Rails Guides are a pretty good example for this.

I don't think there's anything approaching reference documentation at the moment. In my brief foray into the source code, I didn't even see any docstrings or comments. Although the author of the post I linked advises against auto-generating docs (e.g. with tools like codox), I don't think they're too bad but I agree that curated documentation is better. Something like the Bootstrap Documentation really excels at this - providing examples (code and result) for each component.

How does that sound?

[rundis]

To chime in:

• Reference documentation/Api doc: Docstrings would be great, however curated docs potentially using something like AsciiDoc (which can pull in code samples from the source) would probably even more useful
• Topic guides (for plugin devs) would be really great. Example: It took me quite some time to grok how to add an autocomplete feature to a plugin (and still a few blanks..) A brief tutorial/description of something like that would have been a huge timesaver. Other areas that spring to mind are: adding custom content to the sidebar, the steps needed to make a lt client (for language plugins), the complexeties and workarounds when using behaviours to orchestrate composite behaviours (and your mind is wired to a solution that implies a deterministic ordering) :) etc

Anyways. Agreed that this is an important area that would be great to address. I might be able to help out with drafting some content for review etc.

cheers
Magnus

[cldwalker]

There are a few tutorials, which is great. They're a bit disparate at the moment, perhaps there should be a single list with a brief summary of what you can learn from each?

@Robsteranium http://docs.lighttable.com/tutorials/full/ is just one tutorial. I can see how each section could be seen as a separate tutorial but not sure if there's enough text to justify calling each section a tutorial.

I agree that api docs would be useful. There is LightTable/LightTable#1715 to get started on this but I've held off to avoid possible merge conflicts with the atom-shell branch. I'd love to see more guides and tutorials. I'd be happy to review any such efforts

@rundis Your guide ideas sound great. The steps needed to create a language plugin is probably the most in demand as we've gotten requests for it on the mailing list and I've gotten some off the list as well. I usually point them to your blog posts but making them more official would be awesome.

[Robsteranium]

I was actually referring to tutorials that aren't on the docs (e.g. this list on the wiki). Indeed I wonder whether this issue ought to be something like "Port wiki and merge into docs" (rather than just the FAQ)?

Glad to hear API docs stuff is on the radar. Thanks for pointing out that issue. Waiting for atom-shell branch certainly sounds like a sensible way to proceed.

I'm also happy to help out.