Note the upgraded forum! If you are experiencing issues logging in, you may need to reset your password which should send an email. If the email doesn't arrive, be sure to check your spam folder just in case.

Thoughts about Documentation and Knowledge around Fuel

Hi, I have a few issues with FUEL that are not software related:

I learned a great deal by finding solutions here on the forum, especially in answers by @admin, but they are quite hard to find (I'm not using the internal search, but the google index with site:forum.fuelcms... and hard to parse (people just dropping in large chunks of code without formatting, the yellow background of code blocks are weird etc).
Sometimes I bookmark issues, but rarely go back to them - instead I refind them via google.

Another issue is to contribute to the docs, by cloning a full instance of FUEL via Github, change HTML and send pull requests. I know this is how Fuel grew and the docs are partly generated from the sourcecode, but... maybe there is a better way to move forward?

  1. So I wonder if it's worth to explore the possibility to create a community wiki on github to let people share their solutions. I know this has to be moderated, on the other side, with a strict guideline this could be possible, since it's a small community.

  2. Also, without reinventing the wheel, do you think it's possible to move/export the docs to markdown in a separate repo, just one branch, so "everybody" can quickly fix or enhance the docs via Github's Webinterface and send a pull request, that you decide to take in.

These are just loose thoughts, none of this has to happen, since it needs resources that nobody has :), but if...

Comments

  • To be honest, I quite like the cut and thrust of forum discussions to get to a solution. The first answer is not always the best one...

    StackOverflow are quite good at that. I don't often see stuff in there for Fuel but there's lots of CI stuff which is equally applicable.

    I quite like the docs but I do think many of the function definitions could do with more explanations and more detailed examples. Option #2 could help with that...

  • There are really 2 types of docs that the user_guide module generates (and sometimes a combination of them):

    1. Auto-generated documentation based on the comments and using reflection.
    2. View files that can be found in the views/_docs/ folder of their respective Advanced Module. We used a view instead of Markdown because of the flexibility to potentially execute functions to generate the docs or examples (and there is a build in markdown function if you wanted to use it). That decision was made about 8 years ago though and Markdown does seem like a logical choice now with the nice integration with GitHub.

    So in response to moving the files, that would be tricky due to the auto-generating that the user_guide module uses to generate the files and would need to be rebuilt.

  • Yeah, the forum is fine, I set up some user styles and https://chrome.google.com/webstore/detail/syntax-highlighter/glelbammondmpalmahoabfpchnoonnpk helps with syntax highlighting.
    Maybe I'm just spoiled by stack overflow and their up voting/accepted answer feature. :)

    I really like the docs and how it's embedded in the system, it's just so "hard" to contribute and I guess most people have their "heureka" moments when they are working on a project that needs full attention so contributing should be easier. But I can see, that it's hard to refactor this part. I just wanted to put it out here and see what you guys think.

    Thanks for your thoughts!

Sign In or Register to comment.