› ›
CRITICAL SECURITY VERSION UPDATE:
https://github.com/daylightstudio/FUEL-CMS/releases/tag/1.4.13

Thoughts about Documentation and Knowledge around Fuel

marcus_at_localhostmarcus_at_localhost
in Feature Requests

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

  • almostcompletelyalmostcompletely

    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...

  • adminadmin

    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.

  • marcus_at_localhostmarcus_at_localhost

    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.