First impression report - frustration

I am investigating 'forum' apps that I can self host and integrate with for my own purposes. Took me a while, but I finally got discourse installed and started to config and test post. Not a good experience for the install or the chaotic config sections. I understand there are many moving parts, but just not really coherent documentation. I feel that the docs are what make or break a project, because if it is hard to figure out, it gets left behind. That goes for users, admin and development documentation. That is in fact my idea, to use a forum type system AS the source for the app design, docs, tutorials, etc, in a "Living Documentation" (not sure if that is the exact book i read 10 years ago) and CI sort of way.

After some google AI querying, NodeBB was one of the options distilled to. Came to check it out. So far, been rather impressed. The federation idea fits a concept I had just considered today, so that is a huge check mark. Interface is snappy and responsive. I am understanding it as API access, so check. Go to see the docs, seem rather extensive, check, start going through and I am called to help out and contribute, good, good. Find an update that can be made... uhhhhh. Problem. The page does not have the "edit this page" kind of link anywhere on it that I LOVE to see in open projects. It ENCOURAGES fixes for typos and things of that nature. Encourages engagement be it is EASY to go right where one needs to change. I go the github readme, click the link at the bottom for the "Documentation & Installation Instructions" and it takes me to the website version, not another .md file in the repo.

I search around the repo. I am not really a javascript guy, so this is all pretty daunting, but at least it is not php, and that was part of my searching and distilling. I was irritated because after 10 minutes, I still could not find the docs source files. I came here searched the community thinking maybe a post would point me where. Nope. always back to the web version, not the source.

Just now, after writing all the above, I went to github to grab the exact verbiage of "Documentation & Installation Instructions" and in trying to get back to the code base, did a search and I caught a hint, the docs are their own repository! Located at https://github.com/NodeBB/docs of course.

This is just feedback. But actually lines up exactly with my idea and concept. What if when I wanted to edit that page, I click the edit link, it takes me to a forum post/wiki style or some likeness, can edit the wiki, which is now part of the history and that can batch back to github for the update of the site?

I DO understand that the same idea is there related to changing the .md file in github, doing a pull request, etc. However, I happen to understand that. How many people hanging in the forum are NOT familiar with git? What if they just post a question and after other interact and distill the idea it could be used to create a spec, when can then be used by the developers to implement, shows up in git with the history of the original idea and the iterative specing process all recorded in the forum.
CrowdSourced software development process. All documented along the way. Community support, which can spur new understandings, new ideas, tutorials, help all with comments from all and all based on a single source. That is the concept of what I am pursuing. Develop in the open and just keep iterating and improving.

-1 points · 0 comments · view on lemmy.world

0 Comments

jonathanrdd@community.nodebb.org · 1 pts · 302d
[ removed ]