search

borusg / noodle

Noodle - Puppet External Node Classifier and server database
Apache License 2.0
7 stars 2 forks source link

Documentation #10

Open happymcplaksin opened 7 years ago

happymcplaksin commented 7 years ago
tminor commented 5 years ago

Wee!

WDYT about https://yardoc.org/? Or are you thinking more generic operational type documentation?

tminor commented 5 years ago

Oh, heh. I realize now that you probably mean this.

happymcplaksin commented 5 years ago

Oh, heh. I realize now that you probably mean this.

Well, maybe :) First, I'm surprised to see I wrote that much down! And I'm open to anything in terms of making the documentation better. I haven't used YARD before but, Shiley, it's great :)

doc.md is maybe OK for an overview with examples but it's really traditional documentation which covers all the details, explains how to install/configure/run/use/extend/etc. So I'd love any and all help and know you'll have great ideas!

tminor commented 5 years ago

Perhaps yard-sinatra could be a good way for documenting the API? I'll investigate further!

happymcplaksin commented 5 years ago

Thanks! Oh, also, learning/using OpenAPI (AKA Swagger) would probably be dreamy but that might be a bigger/v2 job

tminor commented 4 years ago

Markdown seems like the easiest/most straightforward way to handle documentation. What do you think about Read the Docs? It looks easy to use, but we could just start by creating a docs directory with markdown files in it. Maybe something like this as a start?

docs/
├── configuration.md
├── deployment.md
├── installation.md
└── overview.md
happymcplaksin commented 4 years ago

Really, I'm up for any of these ideas/plans :) Any plan will be better than the current lack of plan/real docs :)