Writing script documentation

Help and Feedback Scripting Support
#1

I am currently working on an SDK for my current project and need to know the best way of writing documentation at the beginning of the module. It’s going to be public so it needs to be detailed and clean.

I can’t really find anything online on how to write it, so I’d like some tips, please!

1 Like
#4

You could take a look at various github documentations.

I’ll include a few here: https://wiki.0q0.eu/ (I helped to work on this one) or Home · sentanos/roblox-js Wiki · GitHub

I would include general info, exact usage, premissions, limitations and then a few examples of it working. Specifically in that order. Write it as if you are doing a informative essay. Like this here: https://wiki.0q0.eu/books/services/page/getdate

2 Likes
#5

This still isn’t exactly what I’m looking for. I’m trying to look for examples now, but I don’t remember it being this hard to find a script that does it :joy:

1 Like
#6

My number one advice for writing documentation is don’t get in your head.
A couple things you need to keep in mind when writing it are:

  • Who is your audience. (Age, Experience…)
  • Are others going to be editing this.
  • What purpose are people using it for ( Education, Quick implementation.)

Depending on these two main points just explain what each function does, giving a brief description for the purpose of the script in its entirety at the top as well as more in depth information about each section keeping the points i made above in mind.

e.g lets assume:

  • Who is your audience = Young, inexperienced with a basic understanding of lua and scripting.
  • Are others going to be editing this = yes but not the core behaviour.
  • What purpose are people using it for = Quick implementation.
    You will want to give a brief introduction with the purpose of the script and a warning not to edit anything unindicated. Then give a brief description of each function and its role as well as show what areas may be edited through highlighting with comments.

Hopefully this demonstrates how you should keep in mind the audience and how this affect the documentation, for any more advice feel free to reply!

3 Likes
#7

My audience is pretty experienced and lots will be forking the SDK. I’m going to quickly try and make some and show it here for some advice.

2 Likes
#8

I suggest MkDocs with Google’s Material Design package.
It just uses Markdown for the pages and just is overall a great way to do documentation.

3 Likes
#9

I already have a documentation website.

I am trying to figure out the best way to do this in a script. Here is what I have so far:

--[[
	Devable SDK: Used to interact with the Devable products API. 
	
	Documentation: 
	Devable.new( String storeId, Options { Bool debugMessages, Bool outputChatMessages, Instance productDirectory } )
		Returns Connection
		Creates a new connection to the store. Engine module is used to handle longpolling with the server.
		
		Connection:LoadProduct( String productId )
		Loads a specific product with a given ID. Bytecode of products scripts is loaded with the interpreter.
		Modules are loaded first. These can then be accessed with "self.Modules.ModuleName" which will lazy load 
		the module and return it to the script. Client bytecode is sent to the client for exection and has 
		access to client and shared modules.
		
		Connection:LoadAllProducts()
		Same as "Connection:LoadProduct" but loads all products automatically.
]]

Thoughts on how I could improve it?

1 Like
#10

Ah well I use this

because it’s very convenient to read.

2 Likes
#11

Personally I’m reading it and it makes perfect sense but you may want to add slightly more detail to (as it’s slightly obscure):

and a reference to anything outside of the script it interacts with so people don’t have to go hunting around so they can interpret the documentation better but that’s more general advice.

1 Like