Forem Creators and Builders 🌱

Cover image for What should Forem use for documentation?

What should Forem use for documentation?

Julianna Tetreault on August 09, 2020

Should Forem continue to use GitDocs for documentation or is there a more user-friendly and easier to use alternative, such as GitBook, that you’d like to see Forem use instead?

Collapse
 
lee profile image
Lee

That is a really good question. If you consider that many Forem's are likely to be created by non devs then what would be the easiest way to consume instructions and get up and running? For me, that is generally a combination of great video tutorials with simple to read, clean documentation. I think Shopify is a great example, as is printful.com πŸ˜ƒ

Collapse
 
juliannatetreault profile image
Julianna Tetreault

Video tutorials in addition to concise documentation are such a powerful combination! Thank you for the input and examples, Lee. πŸ˜„

Collapse
 
vaidehijoshi profile image
Vaidehi Joshi

The videos are an interesting idea, @leewynne! The one thing I will say is that, having worked with "videos as documentation" in the past, they are very hard to keep up with and maintain (if you change one part of the UI, the video immediately is outdated πŸ˜“). I'd almost vote for using videos to highlight different features (the "outdated" video problem still exists here, but you can get away with that more so on pages that describe a feature than on a page that purports itself to be documentation!).

Thread Thread
 
lee profile image
Lee

that's a really good point....!

Thread Thread
 
ben profile image
Ben Halpern

Videos tend to be best for getting started as opposed to deeper issues when you're already started. So maybe if we had a few canonical videos for getting started that we made a point to re-record about once per month?

If we kept the surface area low and actually followed through on updating them, it could be a great component of the guides.

Thread Thread
 
juliannatetreault profile image
Julianna Tetreault

I think that having some "getting started" videos would be really awesome and useful for Forem creators!

Another idea: we could also incorporate GIFs into our guides to help clarify more general issues or issues that don't require an entire video, but maybe a tiny tutorial.

Thread Thread
 
vaidehijoshi profile image
Vaidehi Joshi

@juliannatetreault Yeah I really love the usage of gifs to show where something lives or how to interact with something. Gifs in documentation (when it makes sense) can also be fun! They still take work to update but they're much easier than an entire video.

Thread Thread
 
juliannatetreault profile image
Julianna Tetreault

Yes, my thoughts exactly, @vaidehijoshi ! ✨

Collapse
 
rhymes profile image
rhymes

Great idea!

Adding here that video tutorials should be captioned for accessibility 😊

Collapse
 
turnerj profile image
James Turner

One important aspect for me with documentation (particularly with areas I don't understand) is examples and scenarios. It can help take more abstract concepts and make them more concrete.

I don't know much about documentation tools though from me as a user, I've really liked the documentation that Stripe has (both its very thorough API documentation and its less-API oriented documentation).

Collapse
 
juliannatetreault profile image
Julianna Tetreault

Examples and scenarios can definitely be useful in documentation!

Collapse
 
akhil profile image
Akhil Naidu • Edited

In my perspective, the present documentation is excellent, and refining it regularly is enough for people who are aware of so-called technical knowledge, i.e., experience with ruby on rails, Heroku, and many other production-oriented alternatives.

So the focus should not be on the formal documentation, which Forem already had. Also, it should not be on the informal and static documentation, as some video tutorials - it's tough to update.

The main focus should be on semi-formal documentation, like guides on:

  1. Setting up a Forem development instance in a local machine.
  2. How to migrate a local Forem development instance to Heroku or own VPS or some other alternatives as to the production instance
  3. Advantages and disadvantages of having a Forem instance in VPS, Local machine separately.
  4. Entire development to production of Forem in a single digital ocean droplet or VPS.

This kind of semi-formal documentation, also known as guides 😜, are beneficial to the majority of the less experienced developers or beginners.

I didn't randomly come up with this idea; I am an undergraduate who is working with some of my friends to do something useful in the time of this ongoing pandemic. I always thought of having a blogging platform with twitter-like features but found none. Forem is the best alternative for me to begin. So we decided to work on it but failed 😏, almost three months have been passed but can't have a production-based Forem instance πŸ˜”

Collapse
 
akhil profile image
Akhil Naidu

Also, this kind of guide needs no new platform. I always felt that Dev is a platform for developers to share their knowledge through blogging.

In the case of Forem, I expect such a guide from the Forem team itself. It is a guide that utilizes the potential of Forem; it acts as a showcase on what a Forem instance can do.

Collapse
 
tofraley profile image
Taylor Fraley • Edited

I agree. From what I understand, the Discourse community uses Discourse for their documentation. Maybe Forem could do the same. Use Forem.dev or another Forem site. This would make a lot of sense for living documentation. Discussions can become the documentation. When the discussion becomes too lengthy, it could be summarized into a new post.
Any thoughts on why Forem might not be suitable for this?

Collapse
 
amorpheuz profile image
Yash Dave

I would love to see Docusaurus being used for this. It is highly customizable, takes benefit of md(x in v2), has the same dependencies (Node and Yarn) as DEV and extremely feature-rich!

Collapse
 
juliannatetreault profile image
Julianna Tetreault

I hadn't heard of Docusaurus until now! Thank you for the recommendation. πŸ˜„

Collapse
 
enygmator profile image
Tarun Aditya Thurlapati

I would personally prefer DocFX since I love to use it both as a docs reader and author. And, there is a new version coming out soon which would make it even better.
I like it's UI like TOC (sidebar), search and the way content appears both, on desktop and mobile, equally good.

Collapse
 
juliannatetreault profile image
Julianna Tetreault

Taking into consideration what works well on mobile and what doesn't is great to think about!

Collapse
 
turnerj profile image
James Turner

Just as an aside to the conversations about documentation tools - it probably would make for a really nice post going through pros/cons and general thoughts about the different options you decide between.

Personally I have a few projects where I have little-to-no documentation written and would love to learn about the experience DEV/Forem go through for choosing a documentation tool etc.

Collapse
 
rcarlson profile image
rcarlson

I've always been a fan of readthedocs.io - this is coming from the perspective of a reader, not an author.

Collapse
 
juliannatetreault profile image
Julianna Tetreault

This is worth checking out, thank you!