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?
For further actions, you may consider blocking this person and/or reporting abuse
Top comments (21)
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 😃
Video tutorials in addition to concise documentation are such a powerful combination! Thank you for the input and examples, Lee. 😄
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!).
that's a really good point....!
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.
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.
@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.
Yes, my thoughts exactly, @vaidehijoshi ! ✨
Great idea!
Adding here that video tutorials should be captioned for accessibility 😊
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).
Examples and scenarios can definitely be useful in documentation!
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:
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 😔
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.
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?
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!
I hadn't heard of Docusaurus until now! Thank you for the recommendation. 😄
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.
Taking into consideration what works well on mobile and what doesn't is great to think about!
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.
I've always been a fan of readthedocs.io - this is coming from the perspective of a reader, not an author.
This is worth checking out, thank you!