Looking for ideas on a plugin or small app that ca...
# cfml-general
a
Looking for ideas on a plugin or small app that can be used as a documentation tool to let developers and users document a app for how it works and store info on updates etc?
b
@abhalani If you mean Javadoc-style docs of CFCs and methods, look into DocBox. If you just mean "how to" sort of docs, we just use wikis or markdown files
a
Looking for wiki style burt, DocBox sounds interesting. 👍
b
I'd start here-- with this CLI-based wrapper which is best for automation creation of your code API docs https://www.forgebox.io/view/commandbox-docbox
a
Wow that is cool! Any suggestions on a wiki style that end users can also contribute too with their notes on how the application is to be used?
b
If it's just for internal use, a Git repo of markdown files can get you a lot of mileage. A lot of products like Confluence/JIRA have wikis built in.
👍 1
g
I would add, if I may... If you're going to implement a wiki for documentation (and / or) things like a development methodology and / or coding standards - get the "whole" development team to create them on a wiki, too. I always go with "the majority wins" - unless I just happen to know that "X" sounds great but never works; then I will make a "captain's decision" and say "No". - but also make sure I explain why... The beauty of doing ALL rules - in a wiki - is that they can be changed, easily. The REAL beauty of getting the development team to write their own - is that "they" own the rules. They weren't "just" forced upon them. So they automatically "buy-in" to the agreed standards. Even when they personally agree to a rule or two. Also make sure that any code reviews / PRs follow the same documentation and you MUST not allow any code that doesn't match the standard to "stay" in your code base. "Oh the coding standards say 'tabs of 4 spaces' / 'IFS / LOOPS / ETC start on a new line with a blank line above and below... Or the agreed standard states we will ALWAYS use a service and gateway class - unless it is a report: and then it MUST use the reporting engine.... All emails MUST be sent via the emailService... / etc... and this code we're currently looking at: doesn't follow those rules - you'll need to redo it to match the "standard". This ALSO works - even for a single developer. It has stopped me from my own stupidity at times. My ultimate goal in all this isn't you follow my rules or there will be hel;l to pay - it is; Everyone writes the same code, the same way. So it doesn't matter that "Bob" wrote it - when "I" come to read it / update it / debug it - it reads to me - like I had written it myself. Sorry got a bit off - topic! :D
b
@gavinbaumanis - I'm sure I am not the only one who is curious now... Is your coding standard public anywhere?
j
I used to be a big wiki fan but am leaning more and more towards either a simple README.md file or a /docs dir with markdown files. Just much easier if I want to make a note while coding - I'm already in the editor, so just pop open the file, make the note, done. The more convenient, the more likely someone will actually update things LOL
1
g
@Jim Priest - I really like the Atlassian products - so I really get into things like using tags as metadata for searching, after the fact. so I can search for "XXXX" and see any wiki entries, any commits/PRs and any issues. Their integration with each other is really awesome... and also - the tools / extensions for your favourite editor mean that you can do things like turn a TODO into an issue - from the editor. And I do have quite a few extensi0ns loaded into VSCode - but I use the neoVim plugin, too - so I can do vim "movements" for getting around my code - so the extra IDE bloat doesn't effect the speed of my work.
@brettpr - Not readily - but I "THINK" I might have an older one on a personal backup - that I could use without worrying anything company specific... Please feel free to ping me in a little while as a reminder!
👍 1